@viccydev/pi-fpa 0.7.2 → 0.8.1

package/extensions/fpa-dashboard/module-publisher.ts

@@ -0,0 +1,390 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+import { stableJson } from "../fpa-artifacts/store.ts";
+import type { DashboardWidget } from "./projector.ts";
+import { validateDatasetForWidget } from "./schema.ts";
+
+export type DashboardModuleId = "period-review" | "next-strategy" | "next-forecast" | "execution-evidence";
+export type DashboardModuleStatus = "published" | "awaiting_decision" | "approved" | "changes_requested" | "generating" | "superseded";
+
+export interface DashboardModuleInteraction {
+	kind: "strategy-decision";
+	action_id: string;
+}
+
+export interface DashboardModuleBuild {
+	id: DashboardModuleId;
+	title: string;
+	status: DashboardModuleStatus;
+	source: Record<string, unknown>;
+	widgets: DashboardWidget[];
+	interaction?: DashboardModuleInteraction;
+}
+
+export interface PublishDashboardModuleOptions {
+	cwd: string;
+	module: DashboardModuleBuild;
+	dashboardTitle?: string;
+	expectedDashboardRevision?: string | null;
+	publishedAt?: string;
+}
+
+export interface PublishDashboardModuleResult {
+	dashboardDir: string;
+	dashboardRevision: string;
+	moduleRevision: string;
+	publishedDatasets: number;
+}
+
+export interface TransitionStrategyModuleResult {
+	dashboardRevision: string;
+	moduleRevision: string;
+}
+
+interface DashboardModuleManifestEntry {
+	id: DashboardModuleId;
+	title: string;
+	status: DashboardModuleStatus;
+	updatedAt: string;
+	revision: string;
+	buildReceipt: string;
+	widgets: Array<{ id: string; type: DashboardWidget["type"]; span: DashboardWidget["span"]; dataset: string }>;
+	interaction?: DashboardModuleInteraction;
+}
+
+export interface DashboardManifestV2 {
+	kind: "fpa.dashboard";
+	schemaVersion: 2;
+	title: string;
+	updatedAt: string;
+	dashboardRevision: string;
+	moduleOrder: DashboardModuleId[];
+	modules: Partial<Record<DashboardModuleId, DashboardModuleManifestEntry>>;
+}
+
+const MODULE_IDS: DashboardModuleId[] = ["period-review", "next-strategy", "next-forecast", "execution-evidence"];
+const MODULE_ID_SET = new Set<string>(MODULE_IDS);
+const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,191}\.json$/;
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+async function pathKind(path: string): Promise<"missing" | "directory" | "symlink" | "other"> {
+	try {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink()) return "symlink";
+		if (stat.isDirectory()) return "directory";
+		return "other";
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
+		throw error;
+	}
+}
+
+async function ensureOwnedDirectory(path: string, label: string): Promise<void> {
+	const kind = await pathKind(path);
+	if (kind === "symlink") throw new Error(`${label} must not be a symlink.`);
+	if (kind === "other") throw new Error(`${label} must be a directory.`);
+	if (kind === "missing") await mkdir(path, { recursive: true, mode: 0o700 });
+}
+
+async function atomicWrite(destination: string, contents: string): Promise<void> {
+	const temporary = join(dirname(destination), `.${basename(destination)}.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	let closed = false;
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+		await handle.close();
+		closed = true;
+		await rename(temporary, destination);
+	} catch (error) {
+		if (!closed) await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+		throw error;
+	}
+}
+
+async function appendOnlyWrite(directory: string, destination: string, contents: string): Promise<void> {
+	const temporary = join(directory, `.${basename(destination)}.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	try {
+		await link(temporary, destination);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		if (await readFile(destination, "utf8") !== contents) throw new Error(`Append-only dashboard object ${basename(destination)} already exists with different content.`);
+	} finally {
+		await unlink(temporary).catch(() => undefined);
+	}
+}
+
+async function resolveDashboardDir(cwd: string): Promise<string> {
+	const projectRoot = await realpath(cwd);
+	return join(dirname(projectRoot), ".fpa-dashboard");
+}
+
+function assertModule(module: DashboardModuleBuild): void {
+	if (!MODULE_ID_SET.has(module.id)) throw new Error(`Unsupported dashboard module id "${module.id}".`);
+	if (!module.title?.trim()) throw new Error("Dashboard module title is required.");
+	if (!Array.isArray(module.widgets) || module.widgets.length === 0 || module.widgets.length > 64) throw new Error("Dashboard module must contain between 1 and 64 widgets.");
+	if (module.interaction && (module.id !== "next-strategy" || module.status !== "awaiting_decision")) {
+		throw new Error("Strategy decisions are available only on an awaiting next-strategy module.");
+	}
+	const widgetIds = new Set<string>();
+	for (const widget of module.widgets) {
+		if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(widget.id) || widgetIds.has(widget.id)) throw new Error(`Invalid or duplicate dashboard widget id "${widget.id}".`);
+		widgetIds.add(widget.id);
+		if (!DATASET_FILE_RE.test(widget.dataset)) throw new Error(`Invalid logical dataset name "${widget.dataset}".`);
+		validateDatasetForWidget(widget.type, widget.data);
+	}
+}
+
+export function dashboardModuleBuildFingerprint(module: DashboardModuleBuild): string {
+	assertModule(module);
+	return sha256(stableJson(module));
+}
+
+function dashboardRevision(title: string, moduleOrder: DashboardModuleId[], modules: DashboardManifestV2["modules"]): string {
+	return sha256(stableJson({ title, moduleOrder, modules }));
+}
+
+async function readManifest(path: string): Promise<DashboardManifestV2 | null> {
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;
+		if (parsed.kind !== "fpa.dashboard") throw new Error("Existing dashboard manifest kind is invalid.");
+		if (parsed.schemaVersion === 1) {
+			if (!Array.isArray(parsed.widgets) || typeof parsed.generationId !== "string" || typeof parsed.buildReceipt !== "string") {
+				throw new Error("Legacy dashboard manifest is invalid.");
+			}
+			const updatedAt = typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date(0).toISOString();
+			const legacyEntry: DashboardModuleManifestEntry = {
+				id: "execution-evidence",
+				title: "历史经营闭环",
+				status: "published",
+				updatedAt,
+				revision: parsed.generationId,
+				buildReceipt: parsed.buildReceipt,
+				widgets: parsed.widgets as DashboardModuleManifestEntry["widgets"],
+			};
+			const title = typeof parsed.title === "string" ? parsed.title : "FP&A Dashboard";
+			const modules = { "execution-evidence": legacyEntry };
+			const moduleOrder: DashboardModuleId[] = ["execution-evidence"];
+			return {
+				kind: "fpa.dashboard",
+				schemaVersion: 2,
+				title,
+				updatedAt,
+				dashboardRevision: dashboardRevision(title, moduleOrder, modules),
+				moduleOrder,
+				modules,
+			};
+		}
+		if (parsed.schemaVersion !== 2 || !parsed.modules || !Array.isArray(parsed.moduleOrder)) throw new Error("Dashboard manifest schema is unsupported.");
+		return parsed as unknown as DashboardManifestV2;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+async function normalizeLegacyModuleReceipt(
+	dashboardDir: string,
+	modulesDir: string,
+	current: DashboardManifestV2 | null,
+): Promise<DashboardManifestV2 | null> {
+	const legacy = current?.modules["execution-evidence"];
+	if (!current || !legacy || legacy.buildReceipt.startsWith("modules/")) return current;
+	if (!DATASET_FILE_RE.test(legacy.buildReceipt)) throw new Error("Legacy dashboard build receipt path is invalid.");
+	const sourcePath = join(dashboardDir, legacy.buildReceipt);
+	const stat = await lstat(sourcePath);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Legacy dashboard build receipt must be a regular file.");
+	const old = JSON.parse(await readFile(sourcePath, "utf8")) as { source?: unknown; warnings?: unknown; datasets?: unknown };
+	if (!Array.isArray(old.datasets)) throw new Error("Legacy dashboard build receipt datasets are invalid.");
+	const receipt = {
+		kind: "fpa.dashboard.module.build",
+		schema_version: 1,
+		module_id: "execution-evidence",
+		module_revision: legacy.revision,
+		published_at: legacy.updatedAt,
+		status: legacy.status,
+		source: { ...(old.source && typeof old.source === "object" ? old.source : {}), warnings: old.warnings ?? [], legacy_generation_id: legacy.revision },
+		datasets: old.datasets,
+	};
+	const contents = `${JSON.stringify(receipt, null, 2)}\n`;
+	const filename = `modules/execution-evidence.${legacy.revision}.${sha256(stableJson(receipt))}.json`;
+	await appendOnlyWrite(modulesDir, join(dashboardDir, filename), contents);
+	return { ...current, modules: { ...current.modules, "execution-evidence": { ...legacy, buildReceipt: filename } } };
+}
+
+export async function readDashboardModuleManifest(cwd: string): Promise<DashboardManifestV2 | null> {
+	return readManifest(join(await resolveDashboardDir(cwd), "manifest.json"));
+}
+
+export async function readDashboardModuleSource(cwd: string, moduleId: DashboardModuleId): Promise<Record<string, unknown> | null> {
+	const dashboardDir = await resolveDashboardDir(cwd);
+	const entry = (await readManifest(join(dashboardDir, "manifest.json")))?.modules[moduleId];
+	if (!entry) return null;
+	if (!entry.buildReceipt.startsWith("modules/") || !DATASET_FILE_RE.test(basename(entry.buildReceipt))) throw new Error("Dashboard module build receipt path is invalid.");
+	const path = join(dashboardDir, entry.buildReceipt);
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Dashboard module build receipt must be a regular file.");
+	const receipt = JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;
+	if (receipt.kind !== "fpa.dashboard.module.build" || receipt.module_id !== moduleId || receipt.module_revision !== entry.revision || receipt.status !== entry.status) {
+		throw new Error("Dashboard module build receipt does not match its manifest entry.");
+	}
+	return receipt.source && typeof receipt.source === "object" ? receipt.source as Record<string, unknown> : {};
+}
+
+export async function publishDashboardModule(options: PublishDashboardModuleOptions): Promise<PublishDashboardModuleResult> {
+	assertModule(options.module);
+	const dashboardDir = await resolveDashboardDir(options.cwd);
+	await ensureOwnedDirectory(dashboardDir, "Dashboard directory");
+	const datasetsDir = join(dashboardDir, "datasets");
+	await ensureOwnedDirectory(datasetsDir, "Dashboard datasets directory");
+	const modulesDir = join(dashboardDir, "modules");
+	await ensureOwnedDirectory(modulesDir, "Dashboard modules directory");
+
+	const lockPath = join(dashboardDir, ".module-publish.lock");
+	let lock;
+	try {
+		lock = await open(lockPath, "wx", 0o600);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error("Another dashboard module publication is in progress; retry after reading the current dashboard revision.");
+		throw error;
+	}
+
+	try {
+		const manifestPath = join(dashboardDir, "manifest.json");
+		const current = await normalizeLegacyModuleReceipt(dashboardDir, modulesDir, await readManifest(manifestPath));
+		const currentRevision = current?.dashboardRevision;
+		if (options.expectedDashboardRevision !== undefined && (options.expectedDashboardRevision ?? undefined) !== currentRevision) {
+			throw new Error(`Dashboard revision changed: expected ${options.expectedDashboardRevision}, current ${currentRevision ?? "none"}.`);
+		}
+
+		const publishedAt = options.publishedAt ?? new Date().toISOString();
+		const revision = dashboardModuleBuildFingerprint(options.module);
+		const datasets = options.module.widgets.map((widget) => {
+			const contents = `${JSON.stringify(widget.data, null, 2)}\n`;
+			const digest = sha256(stableJson(widget.data));
+			const logicalBase = widget.dataset.slice(0, -".json".length);
+			const filename = `${options.module.id}.${logicalBase}.${digest}.json`;
+			if (!DATASET_FILE_RE.test(filename)) throw new Error(`Content-addressed dataset name "${filename}" exceeds the dashboard contract.`);
+			return { widget, filename, digest, contents };
+		});
+		for (const dataset of datasets) await appendOnlyWrite(datasetsDir, join(datasetsDir, dataset.filename), dataset.contents);
+
+		const receipt = {
+			kind: "fpa.dashboard.module.build",
+			schema_version: 1,
+			module_id: options.module.id,
+			module_revision: revision,
+			published_at: publishedAt,
+			status: options.module.status,
+			source: options.module.source,
+			datasets: datasets.map(({ widget, filename, digest }) => ({ logical: widget.dataset, filename, sha256: digest })),
+		};
+		const receiptContents = `${JSON.stringify(receipt, null, 2)}\n`;
+		const receiptDigest = sha256(stableJson(receipt));
+		const receiptFilename = `modules/${options.module.id}.${revision}.${receiptDigest}.json`;
+		await appendOnlyWrite(modulesDir, join(dashboardDir, receiptFilename), receiptContents);
+
+		const entry: DashboardModuleManifestEntry = {
+			id: options.module.id,
+			title: options.module.title,
+			status: options.module.status,
+			updatedAt: publishedAt,
+			revision,
+			buildReceipt: receiptFilename,
+			widgets: datasets.map(({ widget, filename }) => ({ id: widget.id, type: widget.type, span: widget.span, dataset: filename })),
+			...(options.module.interaction ? { interaction: options.module.interaction } : {}),
+		};
+		const title = options.dashboardTitle ?? current?.title ?? "FP&A Dashboard";
+		const modules = { ...(current?.modules ?? {}), [options.module.id]: entry };
+		const moduleOrder = current?.moduleOrder.includes(options.module.id)
+			? current.moduleOrder
+			: [...(current?.moduleOrder ?? []), options.module.id];
+		const nextRevision = dashboardRevision(title, moduleOrder, modules);
+		const nextManifest: DashboardManifestV2 = {
+			kind: "fpa.dashboard",
+			schemaVersion: 2,
+			title,
+			updatedAt: publishedAt,
+			dashboardRevision: nextRevision,
+			moduleOrder,
+			modules,
+		};
+		await atomicWrite(manifestPath, `${JSON.stringify(nextManifest, null, 2)}\n`);
+		return { dashboardDir, dashboardRevision: nextRevision, moduleRevision: revision, publishedDatasets: datasets.length };
+	} finally {
+		await lock.close().catch(() => undefined);
+		await unlink(lockPath).catch(() => undefined);
+	}
+}
+
+export async function transitionStrategyModule(
+	cwd: string,
+	input: { actionId: string; status: "approved" | "changes_requested"; transitionedAt?: string },
+): Promise<TransitionStrategyModuleResult> {
+	const dashboardDir = await resolveDashboardDir(cwd);
+	const lockPath = join(dashboardDir, ".module-publish.lock");
+	let lock;
+	try {
+		lock = await open(lockPath, "wx", 0o600);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error("Another dashboard module publication is in progress; retry the strategy decision transition.");
+		throw error;
+	}
+	try {
+		const manifestPath = join(dashboardDir, "manifest.json");
+		const current = await readManifest(manifestPath);
+		if (!current) throw new Error("Dashboard manifest does not exist.");
+		const strategy = current.modules["next-strategy"];
+		if (!strategy || strategy.interaction?.kind !== "strategy-decision" || strategy.interaction.action_id !== input.actionId) {
+			if (strategy?.status === input.status && !strategy.interaction) return { dashboardRevision: current.dashboardRevision, moduleRevision: strategy.revision };
+			throw new Error("Dashboard strategy module does not match this decision action.");
+		}
+		const transitionedAt = input.transitionedAt ?? new Date().toISOString();
+		const revision = sha256(stableJson({ previous_revision: strategy.revision, status: input.status }));
+		if (!strategy.buildReceipt.startsWith("modules/") || !DATASET_FILE_RE.test(basename(strategy.buildReceipt))) throw new Error("Strategy module build receipt path is invalid.");
+		const oldReceiptPath = join(dashboardDir, strategy.buildReceipt);
+		const oldReceiptStat = await lstat(oldReceiptPath);
+		if (oldReceiptStat.isSymbolicLink() || !oldReceiptStat.isFile()) throw new Error("Strategy module build receipt must be a regular file.");
+		const oldReceipt = JSON.parse(await readFile(oldReceiptPath, "utf8")) as Record<string, unknown>;
+		if (oldReceipt.kind !== "fpa.dashboard.module.build" || oldReceipt.module_id !== "next-strategy") throw new Error("Strategy module build receipt is invalid.");
+		const transitionedReceipt = { ...oldReceipt, module_revision: revision, published_at: transitionedAt, status: input.status };
+		const receiptContents = `${JSON.stringify(transitionedReceipt, null, 2)}\n`;
+		const receiptFilename = `modules/next-strategy.${revision}.${sha256(stableJson(transitionedReceipt))}.json`;
+		const modulesDir = join(dashboardDir, "modules");
+		await appendOnlyWrite(modulesDir, join(dashboardDir, receiptFilename), receiptContents);
+		const nextStrategy: DashboardModuleManifestEntry = {
+			...strategy,
+			status: input.status,
+			updatedAt: transitionedAt,
+			revision,
+			buildReceipt: receiptFilename,
+		};
+		delete nextStrategy.interaction;
+		const modules = { ...current.modules, "next-strategy": nextStrategy };
+		const nextDashboardRevision = dashboardRevision(current.title, current.moduleOrder, modules);
+		const next: DashboardManifestV2 = {
+			...current,
+			updatedAt: transitionedAt,
+			dashboardRevision: nextDashboardRevision,
+			modules,
+		};
+		await atomicWrite(manifestPath, `${JSON.stringify(next, null, 2)}\n`);
+		return { dashboardRevision: nextDashboardRevision, moduleRevision: revision };
+	} finally {
+		await lock.close().catch(() => undefined);
+		await unlink(lockPath).catch(() => undefined);
+	}
+}