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

package/assets/packages/cli/src/internal/run-log.ts

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import type { NornFileCoordinator } from "@vimhead.dev/norn/files";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+import { writeJsonAtomically } from "@vimhead.dev/norn-core/atomic-files";
+
+export type NornRunManifestEvent = {
+	readonly at: string;
+	readonly type: string;
+	readonly [key: string]: unknown;
+};
+
+export type NornRunManifest = {
+	readonly id: string;
+	readonly name: string;
+	readonly workflowId: string;
+	readonly runRoot: string;
+	readonly workspace: string;
+	readonly initialCwd: string;
+	readonly startedAt: string;
+	readonly events: readonly NornRunManifestEvent[];
+};
+
+export class NornRunLogger {
+	private isInitialized = false;
+
+	constructor(private readonly input: {
+		readonly manifestPath: string;
+		readonly manifest: Omit<NornRunManifest, "events">;
+		readonly files: NornFileCoordinator;
+	}) {}
+
+	static async load(manifestPath: string, files: NornFileCoordinator): Promise<NornRunLogger> {
+		const manifest = parseManifest(await files.readText(manifestPath));
+		const logger = new NornRunLogger({ manifestPath, manifest, files });
+		logger.isInitialized = true;
+		return logger;
+	}
+
+	async record(event: { readonly type: string; readonly [key: string]: unknown }): Promise<void> {
+		await this.input.files.withExclusiveLock(this.input.manifestPath, async (path) => {
+			let manifest: NornRunManifest;
+			try {
+				manifest = parseManifest(await readFile(path, "utf8"));
+			} catch (error) {
+				if (this.isInitialized || !isNodeError(error) || error.code !== "ENOENT") throw error;
+				manifest = { ...this.input.manifest, events: [] };
+			}
+			if (manifest.id !== this.input.manifest.id) throw new Error("Run manifest identity changed");
+			await writeJsonAtomically(path, { ...manifest, events: [...manifest.events, { ...event, at: new Date().toISOString() }] });
+			this.isInitialized = true;
+		});
+	}
+}
+
+function parseManifest(content: string): NornRunManifest {
+	const manifest = JSON.parse(content) as NornRunManifest;
+	if (!manifest || typeof manifest !== "object" || typeof manifest.id !== "string" || !Array.isArray(manifest.events)) throw new Error("Invalid run manifest");
+	return manifest;
+}

package/assets/packages/cli/src/internal/run-names.ts

@@ -0,0 +1,36 @@
+const ADJECTIVES = [
+	"able", "amber", "brave", "bright", "calm", "clever", "crisp", "daring", "eager", "fair",
+	"fast", "fresh", "gentle", "golden", "grand", "happy", "honest", "jolly", "kind", "lively",
+	"lucky", "merry", "nimble", "noble", "patient", "peaceful", "proud", "quiet", "rapid", "ready",
+	"royal", "sharp", "silent", "silver", "simple", "steady", "sunny", "swift", "tidy", "vivid",
+];
+
+const MODIFIERS = [
+	"anchor", "autumn", "brook", "cedar", "cloud", "copper", "dawn", "ember", "field", "forest",
+	"harbor", "hazel", "hill", "island", "ivory", "jade", "lake", "maple", "meadow", "moon",
+	"north", "ocean", "olive", "pearl", "pine", "rain", "river", "rose", "shadow", "snow",
+	"solar", "spring", "stone", "summer", "thunder", "timber", "valley", "violet", "willow", "winter",
+];
+
+const NOUNS = [
+	"badger", "beacon", "bison", "canvas", "comet", "falcon", "fjord", "fox", "garden", "glade",
+	"grove", "heron", "lantern", "lynx", "marker", "otter", "panda", "planet", "prairie", "raven",
+	"rocket", "sail", "signal", "sparrow", "summit", "tiger", "trail", "voyage", "whale", "wolf",
+	"zephyr", "orchid", "bridge", "castle", "harvest", "mirror", "needle", "quartz", "ripple", "signal",
+];
+
+export function generateRunName(existingNames: ReadonlySet<string>): string {
+	for (let attempt = 0; attempt < 100; attempt++) {
+		const name = `${pick(ADJECTIVES)}-${pick(MODIFIERS)}-${pick(NOUNS)}`;
+		if (!existingNames.has(name)) return name;
+	}
+	while (true) {
+		const suffix = Math.random().toString(36).slice(2, 6);
+		const name = `${pick(ADJECTIVES)}-${pick(MODIFIERS)}-${pick(NOUNS)}-${suffix}`;
+		if (!existingNames.has(name)) return name;
+	}
+}
+
+function pick(values: readonly string[]): string {
+	return values[Math.floor(Math.random() * values.length)] ?? values[0];
+}

package/assets/packages/cli/src/internal/run-resources.ts

@@ -0,0 +1,23 @@
+import { join, resolve } from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { NornRunResources } from "../resources.ts";
+import { NornJsonWorkflowState } from "./state-store.ts";
+
+export async function initializeRunResources(runRoot: string): Promise<{ readonly resources: NornRunResources; readonly state: NornJsonWorkflowState }> {
+	const resources = await NornRunResources.initialize(runRoot);
+	const state = await resources.ensure({
+		name: "workflow-state",
+		kind: "norn.state",
+		configuration: { format: 1, path: "state.json" },
+		async initialize({ files, mode }) {
+			const state = new NornJsonWorkflowState({
+				stateFile: join(resolve(runRoot), "current", "state.json"),
+				files,
+				coordinateMutation: withFileMutationQueue,
+			});
+			await state.initialize(mode);
+			return state;
+		},
+	});
+	return { resources, state };
+}

package/assets/packages/cli/src/internal/run-state.ts

@@ -0,0 +1,380 @@
+import { mkdir, readdir, readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import type { NornRunHealth, NornRunStatus, NornRunOutcomeMetadata, NornRunInfo, NornRunInterruption, NornRunOutcomeInfo, NornRunFailureInfo } from "@vimhead.dev/norn";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+import { readRunLaunchRequest, readOptionalRunResumeRequest, RESUME_START_GRACE_MS } from "./launch-request.ts";
+import { getRunLeaseHealth } from "./run-lease.ts";
+import { writeJsonAtomically } from "@vimhead.dev/norn-core/atomic-files";
+import { createRunFileCoordinator, type NornFileCoordinator } from "@vimhead.dev/norn/files";
+import { runCurrentRoot } from "./run-store.ts";
+
+export const RUN_STATE_FILE_NAME = "run-state.json";
+const LEGACY_RUN_STATE_FILE_NAME = "runtime-state.json";
+
+export function mergeInterruptedWorkflowParams(currentParams: unknown, params: unknown, fields: readonly string[] | undefined): unknown {
+	if (!isRecord(currentParams) || !isRecord(params)) return params;
+	if (fields) {
+		const unsupportedFields = Object.keys(params).filter((field) => !fields.includes(field));
+		if (unsupportedFields.length > 0) throw new Error(`Interrupted workflow params cannot update non-gate fields: ${unsupportedFields.join(", ")}`);
+	}
+	return { ...currentParams, ...params };
+}
+const RUN_STATE_VERSION = 1;
+
+type NornRunWorkflowStep = {
+	readonly workflowId: string;
+	readonly params: unknown;
+	readonly cwd: string;
+	readonly env: Record<string, string>;
+	readonly interruption?: RuntimeInterruption;
+};
+
+type RuntimeInterruption = {
+	readonly status: "pending" | "satisfied";
+	readonly description?: string;
+	readonly fields?: readonly string[];
+};
+
+type NornRunWorkflowCompletion = {
+	readonly workflowId: string;
+	readonly completedAt: string;
+	readonly outcome: { readonly type: "next"; readonly workflowId: string } | { readonly type: "complete" } | { readonly type: "fail" };
+};
+
+type NornRunWorkflowFailure = {
+	readonly workflowId: string;
+	readonly error: string;
+	readonly metadata?: NornRunOutcomeMetadata;
+	readonly failedAt: string;
+};
+
+type NornRunWorkflowOutcome = {
+	readonly workflowId: string;
+	readonly completedAt: string;
+	readonly status: "completed" | "failed";
+	readonly metadata?: NornRunOutcomeMetadata;
+};
+
+export type NornRunState = {
+	readonly version: typeof RUN_STATE_VERSION;
+	readonly id: string;
+	readonly name: string;
+	readonly entrypointWorkflowId: string;
+	readonly workspace: string;
+	readonly configOverride?: unknown;
+	readonly status: NornRunStatus;
+	readonly current: NornRunWorkflowStep | null;
+	readonly lastCompleted: NornRunWorkflowCompletion | null;
+	readonly outcome: NornRunWorkflowOutcome | null;
+	readonly failed: NornRunWorkflowFailure | null;
+	readonly startedAt: string;
+	readonly updatedAt: string;
+};
+
+type CreateNornRunStateInput = {
+	readonly id: string;
+	readonly name: string;
+	readonly entrypointWorkflowId: string;
+	readonly workspace: string;
+	readonly configOverride?: unknown;
+	readonly current: NornRunWorkflowStep;
+	readonly startedAt: string;
+};
+
+export class NornRunStateStore {
+	private readonly path: string;
+	private state: NornRunState;
+	private readonly files: NornFileCoordinator;
+
+	private constructor(input: { readonly path: string; readonly state: NornRunState; readonly files: NornFileCoordinator }) {
+		this.path = input.path;
+		this.state = input.state;
+		this.files = input.files;
+	}
+
+	static async create(runRoot: string, input: CreateNornRunStateInput): Promise<NornRunStateStore> {
+		const now = input.startedAt;
+		const state: NornRunState = {
+			version: RUN_STATE_VERSION,
+			id: input.id,
+			name: input.name,
+			entrypointWorkflowId: input.entrypointWorkflowId,
+			workspace: input.workspace,
+			configOverride: input.configOverride,
+			status: "running",
+			current: input.current,
+			lastCompleted: null,
+			outcome: null,
+			failed: null,
+			startedAt: now,
+			updatedAt: now,
+		};
+		const store = new NornRunStateStore({ path: join(runCurrentRoot(runRoot), RUN_STATE_FILE_NAME), state, files: createRunFileCoordinator(runRoot) });
+		await store.write();
+		return store;
+	}
+
+	static async load(runRoot: string): Promise<NornRunStateStore> {
+		const currentRoot = runCurrentRoot(runRoot);
+		const files = createRunFileCoordinator(runRoot);
+		const state = await files.withExclusiveLock(join(currentRoot, RUN_STATE_FILE_NAME), async (path) => parseNornRunState(await readRunStateFile({ path, legacyPath: join(currentRoot, LEGACY_RUN_STATE_FILE_NAME) })));
+		return new NornRunStateStore({ path: join(currentRoot, RUN_STATE_FILE_NAME), state, files });
+	}
+
+	currentState(): NornRunState {
+		return this.state;
+	}
+
+	async startStep(step: NornRunWorkflowStep): Promise<void> {
+		await this.update({ status: "running", current: step, outcome: null, failed: null });
+	}
+
+	async completeWithNext(completedWorkflowId: string, next: NornRunWorkflowStep): Promise<void> {
+		await this.update({
+			status: "running",
+			current: next,
+			lastCompleted: { workflowId: completedWorkflowId, completedAt: new Date().toISOString(), outcome: { type: "next", workflowId: next.workflowId } },
+			outcome: null,
+			failed: null,
+		});
+	}
+
+	async completeRun(workflowId: string, metadata: NornRunOutcomeMetadata | undefined): Promise<void> {
+		const completedAt = new Date().toISOString();
+		await this.update({
+			status: "completed",
+			current: null,
+			lastCompleted: { workflowId, completedAt, outcome: { type: "complete" } },
+			outcome: { workflowId, completedAt, status: "completed", metadata },
+			failed: null,
+		});
+	}
+
+	async failRun(workflowId: string, metadata: NornRunOutcomeMetadata & { readonly summary: string }): Promise<void> {
+		const failedAt = new Date().toISOString();
+		await this.update({
+			status: "failed",
+			current: null,
+			lastCompleted: { workflowId, completedAt: failedAt, outcome: { type: "fail" } },
+			outcome: { workflowId, completedAt: failedAt, status: "failed", metadata },
+			failed: { workflowId, error: metadata.summary, metadata, failedAt },
+		});
+	}
+
+	async interruptCurrent(params: unknown, interruption: { readonly description: string; readonly fields?: readonly string[] }): Promise<void> {
+		if (!this.state.current) throw new Error("Cannot interrupt run without current step");
+		await this.update({
+			status: "interrupted",
+			current: { ...this.state.current, params, interruption: { status: "pending", ...interruption } },
+			outcome: null,
+			failed: null,
+		});
+	}
+
+	async prepareForResumeAfterRollback(): Promise<void> {
+		if (!this.state.current) throw new Error("Cannot resume a checkpoint without a current step");
+		if (this.state.status === "interrupted") return;
+		if (this.state.status !== "running") throw new Error(`Cannot resume checkpoint with ${this.state.status} status`);
+		await this.update({ status: "pendingResume", outcome: null, failed: null });
+	}
+
+	async stopCurrent(): Promise<void> {
+		if (!this.state.current) throw new Error("Cannot stop run without current step");
+		await this.update({ status: "stopped", outcome: null, failed: null });
+	}
+
+	async replaceCurrentParams(params: unknown): Promise<void> {
+		if (!this.state.current) throw new Error("Cannot resume run without current step");
+		await this.update({
+			status: "running",
+			current: { ...this.state.current, params, interruption: { ...this.state.current.interruption, status: "satisfied" } },
+			outcome: null,
+			failed: null,
+		});
+	}
+
+	async failCurrent(errorOrMetadata: string | NornRunOutcomeMetadata & { readonly summary: string }): Promise<void> {
+		if (!this.state.current) throw new Error("Cannot fail run without current step");
+		const failedAt = new Date().toISOString();
+		const metadata = typeof errorOrMetadata === "string" ? { summary: errorOrMetadata } : errorOrMetadata;
+		await this.update({
+			status: "failed",
+			outcome: { workflowId: this.state.current.workflowId, completedAt: failedAt, status: "failed", metadata },
+			failed: { workflowId: this.state.current.workflowId, error: metadata.summary, metadata, failedAt },
+		});
+	}
+
+	private async update(patch: Partial<NornRunState>): Promise<void> {
+		await this.files.withExclusiveLock(this.path, async (path) => {
+			const current = parseNornRunState(await readRunStateFile({ path, legacyPath: join(dirname(this.path), LEGACY_RUN_STATE_FILE_NAME) }));
+			const next = { ...current, ...patch, updatedAt: new Date().toISOString() };
+			await writeJsonAtomically(path, next);
+			this.state = next;
+		});
+	}
+
+	private async write(): Promise<void> {
+		await mkdir(dirname(this.path), { recursive: true });
+		await this.files.withExclusiveLock(this.path, (path) => writeJsonAtomically(path, this.state));
+	}
+}
+
+export async function listRuns(sessionCwd: string): Promise<NornRunInfo[]> {
+	const runsRoot = join(sessionCwd, ".norn", "runs");
+	let entries;
+	try {
+		entries = await readdir(runsRoot, { withFileTypes: true });
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return [];
+		throw error;
+	}
+
+	const runs = await Promise.all(entries.filter((entry) => entry.isDirectory()).map((entry) => readNornRunInfo(resolve(runsRoot, entry.name))));
+	return runs.filter((run): run is NornRunInfo => run !== undefined).sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+}
+
+export async function getRunInfo(runRoot: string): Promise<NornRunInfo> {
+	try {
+		const resumeRequest = await readOptionalRunResumeRequest(runRoot);
+		const state = parseNornRunState(await readRunStateJson(runCurrentRoot(runRoot)));
+		return {
+			version: state.version,
+			id: state.id,
+			name: state.name,
+			path: runRoot,
+			entrypointWorkflowId: state.entrypointWorkflowId,
+			currentWorkflowId: state.current?.workflowId,
+			status: resumeRequest ? "running" : state.status,
+			health: resumeRequest
+				? await getPendingResumeHealth(runRoot, resumeRequest.createdAt)
+				: await runHealth(runRoot, state.status),
+			interruption: resumeRequest ? undefined : runInterruption(state),
+			outcome: runOutcome(state),
+			failed: runFailure(state),
+			startedAt: state.startedAt,
+			updatedAt: state.updatedAt,
+		};
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		return getLaunchedRunInfo(runRoot);
+	}
+}
+
+export async function resolveRunRoot(sessionCwd: string, run: string): Promise<string> {
+	for (const candidate of runRootCandidates(sessionCwd, run)) {
+		try {
+			if (await readNornRunInfo(candidate)) return candidate;
+		} catch (error) {
+			if (!isNodeError(error) && (!(error instanceof Error) || !error.message.includes("run state"))) throw error;
+		}
+	}
+
+	const runs = await listRuns(sessionCwd);
+	const match = runs.find((entry) => entry.id === run || entry.name === run || entry.path === run || entry.path.endsWith(`/${run}`));
+	if (!match) throw new Error(`Unknown run: ${run}`);
+	return match.path;
+}
+
+function runRootCandidates(sessionCwd: string, run: string): string[] {
+	const candidates = [isAbsolute(run) ? run : resolve(sessionCwd, run)];
+	if (!isAbsolute(run)) candidates.push(resolve(sessionCwd, ".norn", "runs", run));
+	return Array.from(new Set(candidates));
+}
+
+async function getPendingResumeHealth(runRoot: string, requestedAt: string): Promise<NornRunHealth> {
+	const health = await getRunLeaseHealth(runRoot);
+	return health === "healthy" || Date.now() - Date.parse(requestedAt) < RESUME_START_GRACE_MS ? "healthy" : "unhealthy";
+}
+
+async function runHealth(runRoot: string, status: NornRunStatus): Promise<NornRunHealth> {
+	if (status !== "running") return "healthy";
+	return getRunLeaseHealth(runRoot);
+}
+
+async function readNornRunInfo(runRoot: string): Promise<NornRunInfo | undefined> {
+	try {
+		return await getRunInfo(runRoot);
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+async function getLaunchedRunInfo(runRoot: string): Promise<NornRunInfo> {
+	const launchRequest = await readRunLaunchRequest(runRoot);
+	return {
+		version: launchRequest.version,
+		id: launchRequest.id,
+		name: launchRequest.name,
+		path: runRoot,
+		entrypointWorkflowId: launchRequest.workflowId,
+		currentWorkflowId: launchRequest.workflowId,
+		status: "running",
+		health: "healthy",
+		startedAt: launchRequest.createdAt,
+		updatedAt: launchRequest.createdAt,
+	};
+}
+
+async function readRunStateJson(currentRoot: string): Promise<unknown> {
+	return readRunStateFile({ path: join(currentRoot, RUN_STATE_FILE_NAME), legacyPath: join(currentRoot, LEGACY_RUN_STATE_FILE_NAME) });
+}
+
+async function readRunStateFile(input: { readonly path: string; readonly legacyPath: string }): Promise<unknown> {
+	try {
+		return JSON.parse(await readFile(input.path, "utf8"));
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		return JSON.parse(await readFile(input.legacyPath, "utf8"));
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function parseNornRunState(value: unknown): NornRunState {
+	if (!value || typeof value !== "object") throw new Error("Invalid run state");
+	const state = value as Partial<NornRunState> & { rootWorkflowId?: unknown };
+	if (state.version !== RUN_STATE_VERSION) throw new Error(`Unsupported run state version: ${String(state.version)}`);
+	if (typeof state.id !== "string" || state.id.length === 0) throw new Error("Invalid run state id");
+	const normalizedState = state as { name?: string; entrypointWorkflowId?: unknown; rootWorkflowId?: unknown };
+	if (typeof normalizedState.name !== "string" || normalizedState.name.length === 0) normalizedState.name = state.id;
+	if (typeof normalizedState.entrypointWorkflowId !== "string" && typeof normalizedState.rootWorkflowId === "string") normalizedState.entrypointWorkflowId = normalizedState.rootWorkflowId;
+	if (typeof state.entrypointWorkflowId !== "string" || state.entrypointWorkflowId.length === 0) throw new Error("Invalid run state entrypoint workflow id");
+	if (typeof state.workspace !== "string" || state.workspace.length === 0) throw new Error("Invalid run state workspace");
+	if (state.status !== "running" && state.status !== "interrupted" && state.status !== "stopped" && state.status !== "pendingResume" && state.status !== "completed" && state.status !== "failed") throw new Error("Invalid run state status");
+	if (state.status === "interrupted") assertInterruptedNornRunState(state);
+	if (state.status === "stopped" || state.status === "pendingResume") assertResumableNornRunState(state);
+	if (typeof state.startedAt !== "string" || typeof state.updatedAt !== "string") throw new Error("Invalid run state timestamps");
+	return state as NornRunState;
+}
+
+function assertInterruptedNornRunState(state: Partial<NornRunState>): void {
+	if (!state.current) throw new Error("Invalid interrupted run current step");
+	const interruption = state.current.interruption;
+	if (!interruption || interruption.status !== "pending") throw new Error("Invalid run interruption");
+	if (typeof interruption.description !== "string" || interruption.description.length === 0) throw new Error("Invalid run interruption description");
+}
+
+function assertResumableNornRunState(state: Partial<NornRunState>): void {
+	if (!state.current) throw new Error("Invalid resumable run current step");
+}
+
+function runInterruption(state: NornRunState): NornRunInterruption | undefined {
+	if (state.status !== "interrupted" || !state.current?.interruption) return undefined;
+	return {
+		workflowId: state.current.workflowId,
+		params: state.current.params,
+		description: state.current.interruption.description ?? "",
+		fields: state.current.interruption.fields,
+	};
+}
+
+function runOutcome(state: NornRunState): NornRunOutcomeInfo | undefined {
+	return state.outcome ?? undefined;
+}
+
+function runFailure(state: NornRunState): NornRunFailureInfo | undefined {
+	return state.failed ?? undefined;
+}