@farm.js/plugin 0.1.0-beta.0

package/dist/observability/index.js

@@ -0,0 +1,399 @@
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function stableFingerprint(parts) {
+    return parts
+        .map((part) => (part === undefined || part === null ? "na" : String(part).trim()))
+        .join(":");
+}
+function toPositiveInt(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    return Math.max(1, Math.floor(value));
+}
+export function observabilityPlugin(options = {}) {
+    const now = () => Date.now();
+    const service = options.service || process.env.FARM_SERVICE || "farm-app";
+    const environment = options.environment || process.env.NODE_ENV || "development";
+    const tags = options.tags || {};
+    const telemetry = options.telemetry || {};
+    const detection = options.detection || {};
+    const workflow = options.workflow || {};
+    const slowRequestMs = toPositiveInt(telemetry.slowRequestMs ?? options.slowRequestMs, 300);
+    const dedupeWindowMs = toPositiveInt(detection.dedupeWindowMs, 60_000);
+    const logLifecycle = telemetry.logLifecycle ?? options.logLifecycle ?? true;
+    const annotateHtml = telemetry.annotateHtml ?? true;
+    const detectionEnabled = detection.enabled ?? true;
+    const continueOnStepError = workflow.continueOnStepError ?? true;
+    const requestStarts = new WeakMap();
+    const recentIncidentsByFingerprint = new Map();
+    let signalCounter = 0;
+    let incidentCounter = 0;
+    const nextSignalId = () => `sig_${now()}_${(signalCounter++).toString(36)}`;
+    const nextIncidentId = () => `inc_${now()}_${(incidentCounter++).toString(36)}`;
+    const detectionContext = { now };
+    const createDefaultIncident = (signal) => {
+        if (signal.kind === "runtime.error" && signal.error) {
+            return {
+                kind: "runtime-error",
+                title: `Runtime error in ${signal.error.phase}`,
+                severity: "critical",
+                fingerprint: stableFingerprint(["runtime-error", signal.error.phase, signal.error.message]),
+                summary: signal.error.message,
+                metadata: { phase: signal.error.phase, name: signal.error.name },
+            };
+        }
+        if (signal.kind === "request.completed" && signal.request) {
+            if (signal.request.statusCode >= 500) {
+                return {
+                    kind: "request-failure",
+                    title: `Request failure ${signal.request.method} ${signal.request.pathname}`,
+                    severity: "high",
+                    fingerprint: stableFingerprint([
+                        "request-failure",
+                        signal.request.method,
+                        signal.request.pathname,
+                        signal.request.statusCode,
+                    ]),
+                    summary: `Request returned ${signal.request.statusCode}`,
+                    metadata: {
+                        method: signal.request.method,
+                        pathname: signal.request.pathname,
+                        statusCode: signal.request.statusCode,
+                        durationMs: signal.request.durationMs,
+                    },
+                };
+            }
+            if (signal.request.durationMs >= slowRequestMs) {
+                return {
+                    kind: "slow-request",
+                    title: `Slow request ${signal.request.method} ${signal.request.pathname}`,
+                    severity: "medium",
+                    fingerprint: stableFingerprint([
+                        "slow-request",
+                        signal.request.method,
+                        signal.request.pathname,
+                    ]),
+                    summary: `Request took ${signal.request.durationMs}ms`,
+                    metadata: {
+                        method: signal.request.method,
+                        pathname: signal.request.pathname,
+                        statusCode: signal.request.statusCode,
+                        durationMs: signal.request.durationMs,
+                        thresholdMs: slowRequestMs,
+                    },
+                };
+            }
+        }
+        if (signal.kind === "api.response" && signal.api && signal.api.status >= 500) {
+            return {
+                kind: "api-failure",
+                title: `API failure ${signal.api.method} ${signal.api.pathname}`,
+                severity: "high",
+                fingerprint: stableFingerprint([
+                    "api-failure",
+                    signal.api.method,
+                    signal.api.pathname,
+                    signal.api.status,
+                ]),
+                summary: `API returned ${signal.api.status}`,
+                metadata: {
+                    method: signal.api.method,
+                    pathname: signal.api.pathname,
+                    status: signal.api.status,
+                },
+            };
+        }
+        return null;
+    };
+    const shouldDedupe = (fingerprint) => {
+        const seenAt = recentIncidentsByFingerprint.get(fingerprint);
+        if (seenAt && now() - seenAt < dedupeWindowMs) {
+            return true;
+        }
+        recentIncidentsByFingerprint.set(fingerprint, now());
+        return false;
+    };
+    const applyRules = async (signal) => {
+        const rules = detection.rules || [];
+        for (const rule of rules) {
+            const matched = await rule.when(signal, detectionContext);
+            if (!matched)
+                continue;
+            const partial = (await rule.buildIncident?.(signal, detectionContext)) || {};
+            const defaultIncident = createDefaultIncident(signal);
+            return {
+                kind: partial.kind || defaultIncident?.kind || `rule:${rule.id}`,
+                title: partial.title || defaultIncident?.title || `Incident from rule ${rule.id}`,
+                severity: partial.severity || rule.severity || defaultIncident?.severity || "high",
+                fingerprint: partial.fingerprint ||
+                    defaultIncident?.fingerprint ||
+                    stableFingerprint(["rule", rule.id, signal.kind]),
+                summary: partial.summary || defaultIncident?.summary,
+                metadata: {
+                    ...defaultIncident?.metadata,
+                    ...partial.metadata,
+                    ruleId: rule.id,
+                },
+            };
+        }
+        return null;
+    };
+    const resolveIncident = async (signal) => {
+        const mapped = await detection.mapSignalToIncident?.(signal, detectionContext);
+        if (mapped) {
+            return {
+                id: mapped.id || nextIncidentId(),
+                kind: mapped.kind || "mapped-incident",
+                title: mapped.title || "Mapped incident",
+                severity: mapped.severity || "high",
+                fingerprint: mapped.fingerprint || stableFingerprint(["mapped-incident", mapped.kind, signal.kind]),
+                detectedAt: mapped.detectedAt || now(),
+                signalId: mapped.signalId || signal.id,
+                summary: mapped.summary,
+                metadata: mapped.metadata,
+            };
+        }
+        const byRule = await applyRules(signal);
+        const chosen = byRule || createDefaultIncident(signal);
+        if (!chosen)
+            return null;
+        return {
+            id: nextIncidentId(),
+            kind: chosen.kind,
+            title: chosen.title,
+            severity: chosen.severity,
+            fingerprint: chosen.fingerprint,
+            detectedAt: now(),
+            signalId: signal.id,
+            summary: chosen.summary,
+            metadata: chosen.metadata,
+        };
+    };
+    const runWorkflow = async (signal, incident) => {
+        const context = {
+            signal,
+            incident,
+            state: {},
+            fixResult: null,
+        };
+        const callbacks = workflow.callbacks || {};
+        const userActions = workflow.actions || {};
+        const legacyOnIncident = workflow.onIncident;
+        const builtInActions = {
+            notify: async (ctx) => {
+                const onIncident = callbacks.onIncident || legacyOnIncident;
+                if (onIncident) {
+                    await onIncident(ctx);
+                    return;
+                }
+                console.warn(`[obs] incident detected kind=${ctx.incident.kind} severity=${ctx.incident.severity} id=${ctx.incident.id} title="${ctx.incident.title}"`);
+            },
+            log: async (ctx) => {
+                console.log(`[obs] pipeline incident=${ctx.incident.id} kind=${ctx.incident.kind} severity=${ctx.incident.severity}`);
+            },
+        };
+        // Backward-compatibility shims. Prefer defining these steps via workflow.actions.
+        const legacyActions = {};
+        if (workflow.runFix) {
+            legacyActions.fix = async (ctx) => {
+                const result = (await workflow.runFix?.(ctx)) || null;
+                ctx.fixResult = result;
+                return result;
+            };
+        }
+        if (workflow.openPullRequest) {
+            legacyActions.pullRequest = async (ctx) => {
+                if (!ctx.fixResult)
+                    return null;
+                await workflow.openPullRequest?.(ctx);
+                return ctx.fixResult;
+            };
+        }
+        const actionRegistry = {
+            ...builtInActions,
+            ...legacyActions,
+            ...userActions,
+        };
+        const hasFixPath = typeof workflow.runFix === "function";
+        const hasPrPath = typeof workflow.openPullRequest === "function";
+        const pipeline = workflow.pipeline && workflow.pipeline.length > 0
+            ? workflow.pipeline
+            : hasFixPath
+                ? hasPrPath
+                    ? ["notify", "fix", "pullRequest"]
+                    : ["notify", "fix"]
+                : ["notify"];
+        try {
+            await callbacks.onPipelineStart?.(context);
+            for (const step of pipeline) {
+                const action = actionRegistry[step];
+                if (!action) {
+                    const message = `[obs] pipeline step "${step}" is not registered`;
+                    if (!continueOnStepError)
+                        throw new Error(message);
+                    console.warn(message);
+                    continue;
+                }
+                try {
+                    await callbacks.onStepStart?.({ step, context });
+                    const result = await action(context);
+                    if (result !== undefined) {
+                        context.state[step] = result;
+                        if (step === "fix") {
+                            context.fixResult = result;
+                        }
+                    }
+                    await callbacks.onStepComplete?.({ step, context, result });
+                }
+                catch (error) {
+                    await callbacks.onStepError?.({ step, context, error });
+                    const message = `[obs] pipeline step "${step}" failed: ${errorMessage(error)}`;
+                    if (!continueOnStepError)
+                        throw new Error(message);
+                    console.error(message);
+                }
+            }
+            await callbacks.onPipelineComplete?.(context);
+        }
+        catch (error) {
+            await callbacks.onPipelineError?.({ error, context });
+            throw error;
+        }
+    };
+    const processSignal = async (signal) => {
+        if (!detectionEnabled)
+            return;
+        const incident = await resolveIncident(signal);
+        if (!incident)
+            return;
+        if (shouldDedupe(incident.fingerprint))
+            return;
+        try {
+            await runWorkflow(signal, incident);
+        }
+        catch (error) {
+            console.error(`[obs] workflow failed incident=${incident.id} error=${errorMessage(error)}`);
+        }
+    };
+    const createSignal = (kind, payload) => {
+        return {
+            id: nextSignalId(),
+            kind,
+            timestamp: now(),
+            service,
+            environment,
+            tags,
+            ...payload,
+        };
+    };
+    return {
+        name: "@farm.js/plugin-observability",
+        enforce: "post",
+        init() {
+            if (logLifecycle)
+                console.log("[obs] init");
+        },
+        ready() {
+            if (logLifecycle)
+                console.log("[obs] ready");
+        },
+        beforeRequest(req) {
+            const pathname = req.url || "/";
+            const method = req.method || "GET";
+            const requestId = `req_${now()}_${(signalCounter++).toString(36)}`;
+            requestStarts.set(req, {
+                startedAt: now(),
+                method,
+                pathname,
+                requestId,
+            });
+        },
+        async afterResponse(req, res) {
+            const started = requestStarts.get(req);
+            if (!started)
+                return;
+            requestStarts.delete(req);
+            const signal = createSignal("request.completed", {
+                request: {
+                    method: started.method,
+                    pathname: started.pathname,
+                    statusCode: res.statusCode || 200,
+                    durationMs: now() - started.startedAt,
+                    requestId: started.requestId,
+                },
+            });
+            await processSignal(signal);
+        },
+        async afterApiHandler(response, api) {
+            const signal = createSignal("api.response", {
+                api: {
+                    method: api.method,
+                    pathname: api.pathname,
+                    status: response.status,
+                },
+            });
+            await processSignal(signal);
+            return response;
+        },
+        afterRender(html, render) {
+            if (!annotateHtml)
+                return html;
+            const marker = `<!-- observability:path=${render.pathname} route=${render.routePattern ?? "unmatched"} -->`;
+            return html.includes("</body>")
+                ? html.replace("</body>", `${marker}\n</body>`)
+                : `${html}\n${marker}`;
+        },
+        async onError(error) {
+            const message = errorMessage(error.error);
+            const signal = createSignal("runtime.error", {
+                error: {
+                    phase: error.phase,
+                    message,
+                    name: error.error instanceof Error ? error.error.name : undefined,
+                },
+            });
+            await processSignal(signal);
+        },
+        hmrUpdate(update) {
+            if (!logLifecycle)
+                return;
+            console.log(`[obs] hmr file=${update.file} modules=${update.modules.length}`);
+        },
+        async afterBundle(result) {
+            if (logLifecycle) {
+                const state = result.success ? "success" : "failed";
+                console.log(`[obs] bundle ${state} preset=${result.preset} root=${result.root}`);
+            }
+            const signal = createSignal("build.result", {
+                build: {
+                    success: result.success,
+                    preset: result.preset,
+                    root: result.root,
+                },
+            });
+            await processSignal(signal);
+        },
+        async afterNitroBuild(payload) {
+            if (logLifecycle) {
+                console.log(`[obs] nitro preset=${payload.preset} output=${payload.outputDir}`);
+            }
+            const signal = createSignal("nitro.build", {
+                build: {
+                    success: true,
+                    preset: payload.preset,
+                    root: payload.root || process.cwd(),
+                    outputDir: payload.outputDir,
+                },
+            });
+            await processSignal(signal);
+        },
+        shutdown(payload) {
+            if (logLifecycle)
+                console.log(`[obs] shutdown reason=${payload.reason}`);
+            recentIncidentsByFingerprint.clear();
+        },
+    };
+}

package/dist/rsc/build-paths.d.ts

@@ -0,0 +1,3 @@
+/** Resolve a Vite environment outDir without prefixing an already-absolute path. */
+export declare function resolveRscBuildOutputPath(root: string, outDir: string, ...segments: string[]): string;
+//# sourceMappingURL=build-paths.d.ts.map

package/dist/rsc/build-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-paths.d.ts","sourceRoot":"","sources":["../../src/rsc/build-paths.ts"],"names":[],"mappings":"AAEA,oFAAoF;AACpF,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,GAAG,QAAQ,EAAE,MAAM,EAAE,GACpB,MAAM,CAKR"}

package/dist/rsc/build-paths.js

@@ -0,0 +1,8 @@
+import path from "path";
+/** Resolve a Vite environment outDir without prefixing an already-absolute path. */
+export function resolveRscBuildOutputPath(root, outDir, ...segments) {
+    const resolvedOutDir = path.isAbsolute(outDir)
+        ? path.normalize(outDir)
+        : path.resolve(root, outDir);
+    return path.join(resolvedOutDir, ...segments);
+}

package/dist/rsc/entries/client.d.ts

@@ -0,0 +1,14 @@
+import type { EntryContext } from "../types.js";
+/**
+ * Generates the browser entry file.
+ *
+ * This entry file:
+ * - Reads the embedded RSC payload from the HTML (via rsc-html-stream)
+ * - Deserializes it to React elements
+ * - Sets up client-side navigation (intercepts links, handles popstate)
+ * - Registers server action callback if enabled
+ * - Hydrates the page
+ * - Listens for HMR updates from server components
+ */
+export declare function generateClientEntry(ctx: EntryContext): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/rsc/entries/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/rsc/entries/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAiR7D"}