@vimhead.dev/norn-cli 0.1.0-tip.0

package/assets/packages/cli/src/internal/workflow-registry.ts

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import { isWorkflowComplete, isWorkflowFail, isWorkflowNext, type NornAnyWorkflowDeclaration, type NornInspectedWorkflowInfo, type NornJsonSchema, type NornRegisteredWorkflowInfo, type NornRunComplete, type NornDispose, type NornRunFail, type NornWorkflowGateInfo, type NornWorkflowImplementation, type NornRunNext, type NornRunFor, type NornWorkflowParams, type NornWorkflowPluginInfo } from "@vimhead.dev/norn";
+import { assertWorkflowMetadata, isPlainObject, schemaShape, schemaType, unwrapSchema } from "@vimhead.dev/norn/schema";
+
+export type NornRegisteredWorkflow = {
+	workflow: NornAnyWorkflowDeclaration;
+	implementation: NornWorkflowImplementation<NornAnyWorkflowDeclaration, unknown>;
+	configSchema?: z.ZodType;
+	config: unknown;
+	plugin?: NornWorkflowPluginInfo;
+};
+
+export type NornWorkflowStepResult =
+	| NornRunNext
+	| { readonly type: "complete"; readonly workflow: NornAnyWorkflowDeclaration; readonly metadata?: NornRunComplete["metadata"] }
+	| { readonly type: "fail"; readonly workflow: NornAnyWorkflowDeclaration; readonly metadata: NornRunFail["metadata"] };
+
+export class NornWorkflowRegistry {
+	private readonly entries = new Map<string, NornRegisteredWorkflow>();
+
+	register<TWorkflow extends NornAnyWorkflowDeclaration>(
+		workflow: TWorkflow,
+		implementation: NornWorkflowImplementation<TWorkflow, unknown>,
+		metadata: { readonly plugin?: NornWorkflowPluginInfo; readonly configSchema?: z.ZodType; readonly config?: unknown } = {},
+	): NornDispose {
+		if (this.entries.has(workflow.id)) throw new Error(`Workflow already registered: ${workflow.id}`);
+
+		const entry: NornRegisteredWorkflow = {
+			workflow,
+			implementation: implementation as NornWorkflowImplementation<NornAnyWorkflowDeclaration, unknown>,
+			configSchema: metadata.configSchema,
+			config: metadata.configSchema ? metadata.configSchema.parse(defaultConfigInput(metadata.configSchema, metadata.config)) : undefined,
+			plugin: metadata.plugin,
+		};
+		assertWorkflowMetadata(workflow);
+		assertGateWorkflow(workflow);
+		this.entries.set(workflow.id, entry);
+
+		return () => {
+			if (this.entries.get(workflow.id) === entry) this.entries.delete(workflow.id);
+		};
+	}
+
+	list(options: { readonly entrypointsOnly?: boolean } = {}): NornRegisteredWorkflowInfo[] {
+		const entries = options.entrypointsOnly ? this.launchableEntries() : this.sortedEntries();
+		return entries.map((entry) => workflowInfo(entry));
+	}
+
+	inspect(workflowId: string): NornInspectedWorkflowInfo | undefined {
+		const entry = this.entries.get(workflowId);
+		return entry ? inspectedWorkflowInfo(entry) : undefined;
+	}
+
+	launchableEntries(): NornRegisteredWorkflow[] {
+		return this.sortedEntries().filter(({ workflow }) => workflow.isEntrypoint);
+	}
+
+	workflowById(workflowId: string): NornAnyWorkflowDeclaration | undefined {
+		return this.entries.get(workflowId)?.workflow;
+	}
+
+	async describeGate<TWorkflow extends NornAnyWorkflowDeclaration>(
+		workflow: TWorkflow,
+		run: NornRunFor<TWorkflow>,
+		params: unknown,
+		configOverride?: unknown,
+	): Promise<string> {
+		const entry = this.entries.get(workflow.id);
+		if (!entry) throw new Error(`Unknown workflow: ${workflow.id}`);
+		if (!workflow.gate) throw new Error(`Workflow is not gated: ${workflow.id}`);
+		const parsedParams = workflow.params.parse(params) as NornWorkflowParams<TWorkflow>;
+		const parsedConfig = parseExecutionConfig(entry, configOverride);
+		const description = await (entry.implementation as NornWorkflowImplementation<TWorkflow, unknown>).gate?.describe(run, parsedParams, parsedConfig);
+		return validateGateDescription(description ?? workflow.id, workflow.id);
+	}
+
+	async execute<TWorkflow extends NornAnyWorkflowDeclaration>(
+		workflow: TWorkflow,
+		run: NornRunFor<TWorkflow>,
+		params: unknown,
+		configOverride?: unknown,
+	): Promise<NornWorkflowStepResult> {
+		const entry = this.entries.get(workflow.id);
+		if (!entry) throw new Error(`Unknown workflow: ${workflow.id}`);
+
+		const parsedParams = workflow.params.parse(params) as Parameters<NornWorkflowImplementation<TWorkflow, unknown>["execute"]>[1];
+		const parsedConfig = parseExecutionConfig(entry, configOverride);
+		const result = await (entry.implementation as NornWorkflowImplementation<TWorkflow, unknown>).execute(run, parsedParams, parsedConfig);
+		if (isWorkflowNext(result)) return result;
+		if (isWorkflowComplete(result)) return { type: "complete", workflow, metadata: result.metadata };
+		if (isWorkflowFail(result)) return { type: "fail", workflow, metadata: result.metadata };
+		throw new Error(`Workflow returned invalid control result: ${workflow.id}`);
+	}
+
+	private sortedEntries(): NornRegisteredWorkflow[] {
+		return Array.from(this.entries.values()).sort((left, right) => left.workflow.id.localeCompare(right.workflow.id));
+	}
+}
+
+function defaultConfigInput(configSchema: z.ZodType, config: unknown): unknown {
+	if (config !== undefined) return config;
+	return schemaType(unwrapSchema(configSchema)) === "object" ? {} : undefined;
+}
+
+function parseExecutionConfig(entry: NornRegisteredWorkflow, configOverride: unknown): unknown {
+	const pluginConfigOverride = pluginConfigOverrideInput(entry, configOverride);
+	if (!entry.configSchema) {
+		if (pluginConfigOverride !== undefined) throw new Error(`Run config override provided for plugin without config schema: ${entry.plugin?.id ?? entry.workflow.id}`);
+		return undefined;
+	}
+	if (pluginConfigOverride === undefined) return entry.config;
+	const rawConfig = isPlainObject(entry.config) && isPlainObject(pluginConfigOverride)
+		? deepMerge(entry.config, pluginConfigOverride)
+		: pluginConfigOverride;
+	return entry.configSchema.parse(rawConfig);
+}
+
+function pluginConfigOverrideInput(entry: NornRegisteredWorkflow, configOverride: unknown): unknown {
+	if (configOverride === undefined) return undefined;
+	if (!isPlainObject(configOverride)) throw new Error("Run config override must be an object keyed by plugin id");
+	const pluginId = entry.plugin?.id;
+	return pluginId ? configOverride[pluginId] : undefined;
+}
+
+function deepMerge(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown> {
+	const result: Record<string, unknown> = { ...base };
+	for (const [key, value] of Object.entries(override)) {
+		const baseValue = result[key];
+		result[key] = isPlainObject(baseValue) && isPlainObject(value) ? deepMerge(baseValue, value) : value;
+	}
+	return result;
+}
+
+function assertGateWorkflow(workflow: NornAnyWorkflowDeclaration): void {
+	if (!workflow.gate) return;
+	if (workflow.gate.enabled !== true) throw new Error(`Workflow gate must be enabled with true: ${workflow.id}`);
+	if (!workflow.gate.fields) return;
+	const paramsSchema = unwrapSchema(workflow.params);
+	if (schemaType(paramsSchema) !== "object") throw new Error(`Workflow gate fields require object params: ${workflow.id}`);
+	const paramsShape = schemaShape(paramsSchema);
+	for (const field of workflow.gate.fields) {
+		if (!Object.prototype.hasOwnProperty.call(paramsShape, field)) throw new Error(`Unknown workflow gate field ${field}: ${workflow.id}`);
+	}
+}
+
+function validateGateDescription(description: string, workflowId: string): string {
+	const trimmed = description.trim();
+	if (trimmed.length === 0) throw new Error(`Workflow gate description must not be empty: ${workflowId}`);
+	return trimmed;
+}
+
+function inspectedWorkflowInfo(entry: NornRegisteredWorkflow): NornInspectedWorkflowInfo {
+	return {
+		...workflowInfo(entry),
+		paramsSchema: jsonSchema(entry.workflow.params),
+		gate: gateInfo(entry.workflow),
+	};
+}
+
+function workflowInfo(entry: NornRegisteredWorkflow): NornRegisteredWorkflowInfo {
+	return {
+		id: entry.workflow.id,
+		instructions: entry.workflow.instructions,
+		isEntrypoint: entry.workflow.isEntrypoint,
+		isolation: entry.workflow.isolation,
+		plugin: entry.plugin,
+	};
+}
+
+function gateInfo(workflow: NornAnyWorkflowDeclaration): NornWorkflowGateInfo | null {
+	return workflow.gate ? { enabled: true, fields: workflow.gate.fields } : null;
+}
+
+function jsonSchema(schema: z.ZodType): NornJsonSchema {
+	return z.toJSONSchema(schema, { io: "input" }) as NornJsonSchema;
+}

package/assets/packages/cli/src/plugin-loader.ts

@@ -0,0 +1,412 @@
+import { access, readFile, readdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createJiti } from "jiti/static";
+import * as typeboxModule from "typebox";
+import { z } from "zod";
+import * as zodModule from "zod";
+import * as nornModule from "@vimhead.dev/norn";
+import * as nornFilesModule from "@vimhead.dev/norn/files";
+import * as nornSchemaModule from "@vimhead.dev/norn/schema";
+import * as nornSeerModule from "@vimhead.dev/norn/seer";
+import { isWorkflowPlugin, type NornDispose, type NornPluginDiagnostic, type NornProjectInfo, type NornProjectInspection, type NornProjectPluginInfo, type NornWorkflowCatalogInfo, type NornWorkflowInspection, type NornWorkflowPlugin, type NornWorkflowPluginInfo } from "@vimhead.dev/norn";
+import { errorMessage, NornProjectLoadError } from "./internal/errors.ts";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+import { NornMemoryWorkflowState } from "./internal/state-store.ts";
+import { NornWorkflowRegistry, type NornRegisteredWorkflow } from "./internal/workflow-registry.ts";
+import { schemaType, unwrapSchema } from "@vimhead.dev/norn/schema";
+import { resolveSeerModeConfig, type NornResolvedSeerModeConfig } from "@vimhead.dev/norn/seer";
+
+export const NORN_PROJECT_FILE_NAME = "norn.project.json";
+
+const seerModeConfigSchema = z.object({
+	writableRoots: z.array(z.string().min(1)).min(1),
+});
+const nornConfigSchema = z.object({
+	plugins: z.array(z.string().min(1)).default([]),
+	includes: z.array(z.string().min(1)).default([]),
+	config: z.record(z.string(), z.unknown()).default({}),
+});
+const nornProjectConfigSchema = nornConfigSchema.extend({
+	version: z.literal(1).default(1),
+	seerMode: seerModeConfigSchema.optional(),
+});
+
+type NornConfig = z.output<typeof nornConfigSchema> & { readonly seerMode?: never };
+type NornProjectConfig = z.output<typeof nornProjectConfigSchema>;
+
+type NornConfigFile = {
+	readonly path: string;
+	readonly root: string;
+	readonly config: NornConfig;
+};
+
+export type NornProject = {
+	readonly cwd: string;
+	readonly projectPath: string;
+	readonly projectRoot: string;
+	readonly configPath: string;
+	readonly configRoot: string;
+	readonly config: NornProjectConfig;
+	readonly configFiles: readonly NornConfigFile[];
+	readonly projectConfig: Record<string, unknown>;
+	readonly seerMode?: NornResolvedSeerModeConfig;
+};
+
+export type NornLoadedProject = NornProject & {
+	readonly plugins: readonly NornWorkflowPlugin[];
+	readonly pluginInfos: readonly NornProjectPluginInfo[];
+	readonly registry: NornWorkflowRegistry;
+	readonly workflows: readonly NornRegisteredWorkflow[];
+	readonly state: NornMemoryWorkflowState;
+};
+
+type LoadedNornWorkflowPlugin = {
+	readonly plugin: NornWorkflowPlugin;
+	readonly info: NornProjectPluginInfo;
+};
+
+export async function loadNornProject(cwd: string): Promise<NornLoadedProject> {
+	const { project, diagnostics } = await collectNornProject(cwd);
+	if (diagnostics.length > 0) throw new NornProjectLoadError({ diagnostics });
+	return project;
+}
+
+export async function discoverNornProject(cwd: string): Promise<NornProjectInspection & NornWorkflowCatalogInfo> {
+	const { project, diagnostics } = await collectNornProject(cwd);
+	return { project: buildProjectInfo(project), workflows: project.registry.list(), isComplete: diagnostics.length === 0, diagnostics };
+}
+
+export async function inspectNornWorkflow(input: { readonly cwd: string; readonly workflowId: string }): Promise<NornWorkflowInspection> {
+	const { project, diagnostics } = await collectNornProject(input.cwd);
+	const summary = project.registry.list().find(workflow => workflow.id === input.workflowId);
+	if (!summary) {
+		if (diagnostics.length === 0) throw new Error(`Unknown workflow: ${input.workflowId}`);
+		return { workflow: null, isComplete: false, diagnostics };
+	}
+	const info = summary.plugin;
+	if (!info?.path || !info.configPath) throw new Error(`Loaded workflow lacks plugin source: ${input.workflowId}`);
+	try {
+		return { workflow: project.registry.inspect(input.workflowId) ?? null, isComplete: diagnostics.length === 0, diagnostics };
+	} catch (error) {
+		return { workflow: null, isComplete: false, diagnostics: [...diagnostics, createPluginDiagnostic({
+			source: { configPath: info.configPath, pluginPath: info.path, pluginId: info.id },
+			workflowId: input.workflowId, stage: "schema", error,
+		})] };
+	}
+}
+
+function buildProjectInfo(project: NornLoadedProject): NornProjectInfo {
+	return {
+		cwd: project.cwd, projectPath: project.projectPath, projectRoot: project.projectRoot,
+		configPath: project.configPath, configRoot: project.configRoot,
+		configFiles: project.configFiles.map(file => file.path), plugins: project.pluginInfos,
+		seerMode: project.seerMode ?? null,
+	};
+}
+
+export async function findNornProject(cwd: string): Promise<NornProject> {
+	const projectPath = await findNearestNornProject(cwd);
+	const projectRootConfig = await readNornProjectConfigFile(projectPath);
+	const configFiles = await loadIncludedNornConfigFiles(projectRootConfig, new Set([projectRootConfig.path]));
+	return {
+		cwd: resolve(cwd),
+		projectPath: projectRootConfig.path,
+		projectRoot: projectRootConfig.root,
+		configPath: projectRootConfig.path,
+		configRoot: projectRootConfig.root,
+		config: projectRootConfig.config,
+		configFiles,
+		projectConfig: mergeProjectConfig(configFiles),
+		seerMode: resolveSeerModeConfig({ configPath: projectRootConfig.path, configRoot: projectRootConfig.root, seerMode: projectRootConfig.config.seerMode }),
+	};
+}
+
+async function findNearestNornProject(cwd: string): Promise<string> {
+	let current = resolve(cwd);
+	while (true) {
+		const projectPath = join(current, NORN_PROJECT_FILE_NAME);
+		try {
+			await access(projectPath);
+			return projectPath;
+		} catch (error) {
+			if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		}
+		const parent = dirname(current);
+		if (parent === current) throw new Error(`Could not find ${NORN_PROJECT_FILE_NAME} from ${cwd}`);
+		current = parent;
+	}
+}
+
+type NornProjectConfigFile = {
+	readonly path: string;
+	readonly root: string;
+	readonly config: NornProjectConfig;
+};
+
+async function loadIncludedNornConfigFiles(projectFile: NornProjectConfigFile, visitedPaths: Set<string>): Promise<NornConfigFile[]> {
+	const includedConfigFiles = await Promise.all(projectFile.config.includes.map(async (includePath) => {
+		const configPaths = await expandIncludePath(projectFile.root, includePath);
+		return Promise.all(configPaths.map(readNornConfigFile));
+	}));
+	const descendants = await Promise.all(includedConfigFiles.flat().map((includedConfigFile) => loadNornConfigTree(includedConfigFile, visitedPaths)));
+	return [createProjectConfigEntry(projectFile), ...descendants.flat()];
+}
+
+async function loadNornConfigTree(configFile: NornConfigFile, visitedPaths: Set<string>): Promise<NornConfigFile[]> {
+	if (visitedPaths.has(configFile.path)) return [];
+	visitedPaths.add(configFile.path);
+	const includedConfigFiles = await Promise.all(configFile.config.includes.map(async (includePath) => {
+		const configPaths = await expandIncludePath(configFile.root, includePath);
+		return Promise.all(configPaths.map(readNornConfigFile));
+	}));
+	const descendants = await Promise.all(includedConfigFiles.flat().map((includedConfigFile) => loadNornConfigTree(includedConfigFile, visitedPaths)));
+	return [configFile, ...descendants.flat()];
+}
+
+async function readNornProjectConfigFile(path: string): Promise<NornProjectConfigFile> {
+	const config = nornProjectConfigSchema.parse(JSON.parse(await readFile(path, "utf8")));
+	return { path, root: dirname(path), config };
+}
+
+async function readNornConfigFile(path: string): Promise<NornConfigFile> {
+	const config = nornConfigSchema.parse(JSON.parse(await readFile(path, "utf8")));
+	return { path, root: dirname(path), config };
+}
+
+function createProjectConfigEntry(projectFile: NornProjectConfigFile): NornConfigFile {
+	return {
+		path: projectFile.path,
+		root: projectFile.root,
+		config: {
+			plugins: projectFile.config.plugins,
+			includes: projectFile.config.includes,
+			config: projectFile.config.config,
+		},
+	};
+}
+
+type NornPluginSource = Pick<NornPluginDiagnostic, "configPath" | "pluginPath" | "pluginId">;
+type ImportedNornPlugin = { readonly plugin: NornWorkflowPlugin; readonly source: NornPluginSource };
+
+async function collectNornProject(cwd: string): Promise<{ readonly project: NornLoadedProject; readonly diagnostics: NornPluginDiagnostic[] }> {
+	const project = await findNornProject(cwd);
+	const imported = await importWorkflowPlugins(project);
+	const diagnostics = [...imported.diagnostics];
+	const registry = new NornWorkflowRegistry();
+	const state = new NornMemoryWorkflowState();
+	const loaded: LoadedNornWorkflowPlugin[] = [];
+	const conflicts = collectPluginConflicts(imported.plugins);
+	for (const candidate of imported.plugins) {
+		const pluginConflicts = conflicts.get(candidate);
+		if (pluginConflicts) {
+			diagnostics.push(...pluginConflicts);
+			continue;
+		}
+		const result = registerProjectPlugin({ candidate, project, registry, state });
+		diagnostics.push(...result.diagnostics);
+		if (result.loaded) loaded.push(result.loaded);
+	}
+	return {
+		project: { ...project, plugins: loaded.map(entry => entry.plugin), pluginInfos: loaded.map(entry => entry.info), registry, workflows: registry.launchableEntries(), state },
+		diagnostics,
+	};
+}
+
+function collectPluginConflicts(plugins: readonly ImportedNornPlugin[]): Map<ImportedNornPlugin, NornPluginDiagnostic[]> {
+	const byPluginId = new Map<string, ImportedNornPlugin[]>();
+	const byWorkflowId = new Map<string, ImportedNornPlugin[]>();
+	for (const candidate of plugins) {
+		const id = candidate.plugin.manifest.id;
+		byPluginId.set(id, [...(byPluginId.get(id) ?? []), candidate]);
+		for (const workflowId of new Set(Object.values(candidate.plugin.manifest.workflows).map(workflow => workflow.id))) {
+			byWorkflowId.set(workflowId, [...(byWorkflowId.get(workflowId) ?? []), candidate]);
+		}
+	}
+	const conflicts = new Map<ImportedNornPlugin, NornPluginDiagnostic[]>();
+	for (const [pluginId, candidates] of byPluginId) {
+		if (candidates.length < 2) continue;
+		for (const candidate of candidates) conflicts.set(candidate, [createPluginDiagnostic({
+			source: candidate.source, workflowId: null, stage: "duplicate",
+			error: new Error(`Duplicate Norn plugin id: ${pluginId} (${candidates.map(other => other.source.pluginPath).join(", ")})`),
+		})]);
+	}
+	for (const [workflowId, candidates] of byWorkflowId) {
+		const distinctPlugins = candidates.filter(candidate => byPluginId.get(candidate.plugin.manifest.id)?.length === 1);
+		if (distinctPlugins.length < 2) continue;
+		for (const candidate of distinctPlugins) conflicts.set(candidate, [...(conflicts.get(candidate) ?? []), createPluginDiagnostic({
+			source: candidate.source, workflowId, stage: "duplicate",
+			error: new Error(`Workflow already registered: ${workflowId} (${distinctPlugins.map(other => other.source.pluginPath).join(", ")})`),
+		})]);
+	}
+	return conflicts;
+}
+
+async function importWorkflowPlugins(project: NornProject): Promise<{ readonly plugins: ImportedNornPlugin[]; readonly diagnostics: NornPluginDiagnostic[] }> {
+	const plugins: ImportedNornPlugin[] = [];
+	const diagnostics: NornPluginDiagnostic[] = [];
+	for (const configFile of project.configFiles) {
+		const jiti = createJiti(pathToFileURL(configFile.path).href, { moduleCache: false, virtualModules: nornWorkflowVirtualModules() });
+		for (const pluginPath of configFile.config.plugins) {
+			const source: NornPluginSource = { configPath: configFile.path, pluginPath: resolveConfigPath(configFile.root, pluginPath), pluginId: null };
+			let stage: NornPluginDiagnostic["stage"] = "import";
+			try {
+				const module = await jiti.import(pathToFileURL(source.pluginPath).href) as { default?: unknown };
+				stage = "declaration";
+				if (!isWorkflowPlugin(module?.default)) throw new Error(`Norn plugin must be the default export: ${source.pluginPath}`);
+				plugins.push({ plugin: module.default, source: { ...source, pluginId: module.default.manifest.id } });
+			} catch (error) {
+				diagnostics.push(createPluginDiagnostic({ source, workflowId: null, stage, error }));
+			}
+		}
+	}
+	return { plugins, diagnostics };
+}
+
+function registerProjectPlugin(input: {
+	readonly candidate: ImportedNornPlugin;
+	readonly project: NornProject;
+	readonly registry: NornWorkflowRegistry;
+	readonly state: NornMemoryWorkflowState;
+}): { readonly loaded: LoadedNornWorkflowPlugin | null; readonly diagnostics: NornPluginDiagnostic[] } {
+	const { plugin, source } = input.candidate;
+	const diagnostics: NornPluginDiagnostic[] = [];
+	const unregister: NornDispose[] = [];
+	let stage: NornPluginDiagnostic["stage"] = "config";
+	try {
+		const configInput = input.project.projectConfig[plugin.manifest.id];
+		if (!plugin.manifest.config && configInput !== undefined) throw new Error(`Norn config provided for plugin without config schema: ${plugin.manifest.id}`);
+		const config = plugin.manifest.config ? plugin.manifest.config.parse(defaultConfigInput(plugin.manifest.config, configInput)) : undefined;
+		stage = "schema";
+		const info: NornProjectPluginInfo = {
+			id: plugin.manifest.id, path: source.pluginPath, configPath: source.configPath,
+			configSchema: plugin.manifest.config ? z.toJSONSchema(plugin.manifest.config, { io: "input" }) : null, config,
+		};
+		stage = "implementation";
+		const implementation = typeof plugin.implementation === "function" ? plugin.implementation({ cwd: input.project.cwd, state: input.state }) : plugin.implementation;
+		for (const [key, workflow] of Object.entries(plugin.manifest.workflows)) {
+			stage = "implementation";
+			try {
+				const workflowImplementation = implementation.workflows?.[key];
+				if (typeof workflowImplementation?.execute !== "function") throw new Error(`Missing implementation for workflow ${workflow.id}`);
+				stage = "duplicate";
+				if (input.registry.workflowById(workflow.id)) throw new Error(`Workflow already registered: ${workflow.id}`);
+				stage = "declaration";
+				unregister.push(input.registry.register(workflow, workflowImplementation, { plugin: workflowPluginInfo(info), configSchema: plugin.manifest.config, config }));
+			} catch (error) {
+				diagnostics.push(createPluginDiagnostic({ source, workflowId: workflow.id, stage: error instanceof z.ZodError ? "config" : stage, error }));
+			}
+		}
+		if (diagnostics.length === 0) return { loaded: { plugin, info }, diagnostics };
+	} catch (error) {
+		diagnostics.push(createPluginDiagnostic({ source, workflowId: null, stage, error }));
+	}
+	for (const dispose of unregister) dispose();
+	return { loaded: null, diagnostics };
+}
+
+function createPluginDiagnostic(input: {
+	readonly source: NornPluginSource;
+	readonly workflowId: string | null;
+	readonly stage: NornPluginDiagnostic["stage"];
+	readonly error: unknown;
+}): NornPluginDiagnostic {
+	return {
+		...input.source, workflowId: input.workflowId, stage: input.stage, message: errorMessage(input.error),
+		issues: input.error instanceof z.ZodError ? input.error.issues.map(issue => ({
+			path: issue.path.map(part => typeof part === "symbol" ? String(part) : part), code: issue.code, message: issue.message,
+		})) : [],
+	};
+}
+
+function workflowPluginInfo(info: NornProjectPluginInfo): NornWorkflowPluginInfo {
+	return { id: info.id, path: info.path, configPath: info.configPath };
+}
+
+function nornWorkflowVirtualModules(): Record<string, unknown> {
+	return {
+		"@vimhead.dev/norn": nornModule,
+		"@vimhead.dev/norn/files": nornFilesModule,
+		"@vimhead.dev/norn/schema": nornSchemaModule,
+		"@vimhead.dev/norn/seer": nornSeerModule,
+		typebox: typeboxModule,
+		zod: zodModule,
+	};
+}
+
+function mergeProjectConfig(configFiles: readonly NornConfigFile[]): Record<string, unknown> {
+	const [projectFile, ...reusableConfigFiles] = configFiles;
+	let reusableConfig: Record<string, unknown> = {};
+	for (const configFile of reusableConfigFiles) {
+		reusableConfig = mergeReusableConfigObjects(reusableConfig, configFile.config.config, ["config"]);
+	}
+	return mergeProjectConfigObjects(reusableConfig, projectFile?.config.config ?? {});
+}
+
+function mergeReusableConfigObjects(base: Record<string, unknown>, override: Record<string, unknown>, path: readonly string[]): Record<string, unknown> {
+	const result: Record<string, unknown> = { ...base };
+	for (const [key, overrideValue] of Object.entries(override)) {
+		result[key] = Object.prototype.hasOwnProperty.call(result, key)
+			? mergeReusableConfigValue(result[key], overrideValue, [...path, key])
+			: overrideValue;
+	}
+	return result;
+}
+
+function mergeReusableConfigValue(base: unknown, override: unknown, path: readonly string[]): unknown {
+	if (isPlainObject(base) && isPlainObject(override)) return mergeReusableConfigObjects(base, override, path);
+	if (JSON.stringify(base) === JSON.stringify(override)) return base;
+	throw new Error(`Conflicting Norn reusable config at ${path.join(".")}`);
+}
+
+function mergeProjectConfigObjects(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown> {
+	const result: Record<string, unknown> = { ...base };
+	for (const [key, overrideValue] of Object.entries(override)) {
+		result[key] = isPlainObject(result[key]) && isPlainObject(overrideValue)
+			? mergeProjectConfigObjects(result[key], overrideValue)
+			: overrideValue;
+	}
+	return result;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function defaultConfigInput(configSchema: z.ZodType, config: unknown): unknown {
+	if (config !== undefined) return config;
+	return schemaType(unwrapSchema(configSchema)) === "object" ? {} : undefined;
+}
+
+async function expandIncludePath(configRoot: string, includePath: string): Promise<string[]> {
+	const resolvedIncludePath = resolveConfigPath(configRoot, includePath);
+	if (!hasGlobSegment(includePath)) return [resolvedIncludePath];
+	return expandGlobSegments(isAbsolute(includePath) ? sep : configRoot, splitPathSegments(includePath));
+}
+
+async function expandGlobSegments(root: string, segments: readonly string[]): Promise<string[]> {
+	if (segments.length === 0) return [root];
+	const [segment, ...remainingSegments] = segments;
+	if (segment === "*") {
+		const entries = await readdir(root, { withFileTypes: true });
+		const expanded = await Promise.all(entries
+			.filter((entry) => entry.isDirectory())
+			.sort((left, right) => left.name.localeCompare(right.name))
+			.map((entry) => expandGlobSegments(join(root, entry.name), remainingSegments)));
+		return expanded.flat();
+	}
+	return expandGlobSegments(join(root, segment), remainingSegments);
+}
+
+function resolveConfigPath(configRoot: string, path: string): string {
+	if (path.length === 0) throw new Error("Norn path must not be empty");
+	return isAbsolute(path) ? path : resolve(configRoot, path);
+}
+
+function hasGlobSegment(path: string): boolean {
+	return splitPathSegments(path).includes("*");
+}
+
+function splitPathSegments(path: string): string[] {
+	return path.split(/[\\/]+/).filter((segment) => segment.length > 0 && segment !== ".");
+}

package/assets/packages/cli/src/resources.ts

@@ -0,0 +1,67 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { createRunFileCoordinator, type NornFileCoordinator } from "@vimhead.dev/norn/files";
+import type { NornResourceDefinition, NornResources } from "@vimhead.dev/norn";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+import { writeJsonAtomically } from "@vimhead.dev/norn-core/atomic-files";
+
+const definitionSchema = z.strictObject({ name: z.string(), kind: z.string().min(1), configuration: z.json() });
+const recordSchema = definitionSchema.extend({ isInitialized: z.boolean() });
+
+export class NornRunResources implements NornResources {
+	readonly files: NornFileCoordinator;
+	private readonly entries = new Map<string, { readonly definition: z.output<typeof definitionSchema>; readonly value: Promise<unknown> }>();
+
+	private constructor(private readonly runRoot: string) {
+		this.files = createRunFileCoordinator(runRoot);
+	}
+
+	static async initialize(runRoot: string): Promise<NornRunResources> {
+		const resources = new NornRunResources(resolve(runRoot));
+		await mkdir(join(resources.runRoot, "current", "resources"), { recursive: true });
+		return resources;
+	}
+
+	async ensure<T>(definition: NornResourceDefinition<T>): Promise<T> {
+		if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(definition.name)) throw new Error(`Invalid resource name: ${definition.name}`);
+		const identity = definitionSchema.parse({ name: definition.name, kind: definition.kind, configuration: definition.configuration });
+		const existing = this.entries.get(definition.name);
+		if (existing) {
+			if (!isDeepStrictEqual(existing.definition, identity)) throw new Error(`Incompatible resource definition: ${definition.name}`);
+			return existing.value as Promise<T>;
+		}
+		const value = this.initializeResource(definition, identity);
+		const entry = { definition: identity, value };
+		this.entries.set(definition.name, entry);
+		try {
+			return await value;
+		} catch (error) {
+			if (this.entries.get(definition.name) === entry) this.entries.delete(definition.name);
+			throw error;
+		}
+	}
+
+	private async initializeResource<T>(definition: NornResourceDefinition<T>, identity: z.output<typeof definitionSchema>): Promise<T> {
+		const directory = join(this.runRoot, "current", "resources", definition.name);
+		await mkdir(directory, { recursive: true });
+		return this.files.withExclusiveLock(join(directory, "definition.json"), async (path) => {
+			let stored: z.output<typeof recordSchema> | undefined;
+			try {
+				stored = recordSchema.parse(JSON.parse(await readFile(path, "utf8")));
+			} catch (error) {
+				if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+			}
+			if (stored) {
+				const { isInitialized: _isInitialized, ...storedIdentity } = stored;
+				if (!isDeepStrictEqual(storedIdentity, identity)) throw new Error(`Incompatible resource definition: ${definition.name}`);
+			} else {
+				await writeJsonAtomically(path, { ...identity, isInitialized: false });
+			}
+			const value = await definition.initialize({ directory, files: this.files, mode: stored?.isInitialized ? "open" : "create" });
+			if (!stored?.isInitialized) await writeJsonAtomically(path, { ...identity, isInitialized: true });
+			return value;
+		});
+	}
+}

package/assets/packages/core/src/agent-protocol.ts

@@ -0,0 +1 @@
+export const AGENT_RESPONSE_TOOL_NAME = "pi_workflows_agent_response";

package/assets/packages/core/src/atomic-files.ts

@@ -0,0 +1,24 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { isNodeError } from "./errors.ts";
+
+export async function writeJsonAtomically(path: string, value: unknown): Promise<void> {
+	await writeTextAtomically(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function writeTextAtomically(path: string, content: string): Promise<void> {
+	await mkdir(dirname(path), { recursive: true });
+	let existingMode: number | undefined;
+	try { existingMode = (await stat(path)).mode & 0o777; }
+	catch (error) { if (!isNodeError(error) || error.code !== "ENOENT") throw error; }
+	const tmpPath = `${path}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(tmpPath, content, { encoding: "utf8", mode: existingMode });
+		if (existingMode !== undefined) await chmod(tmpPath, existingMode);
+		await rename(tmpPath, path);
+	} catch (error) {
+		await rm(tmpPath, { force: true }).catch(() => undefined);
+		throw error;
+	}
+}