@n-dx/core 0.1.0

package/packages/web/dist/server/routes-features.js

@@ -0,0 +1,245 @@
+/**
+ * Feature toggles API routes.
+ *
+ * Manages feature flags stored in `.n-dx.json` under the `features` key.
+ * Flags are organized by package (sourcevision, rex, hench) and control
+ * experimental or problematic features across the n-dx toolkit.
+ *
+ * GET /api/features   — current feature flags with metadata
+ * PUT /api/features   — update feature flags
+ */
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { jsonResponse, errorResponse, readBody } from "./types.js";
+/**
+ * Central registry of all feature toggles across n-dx packages.
+ * Add new features here as they are developed.
+ */
+const FEATURE_REGISTRY = [
+    // ── SourceVision ──────────────────────────────────────────────────
+    {
+        key: "sourcevision.callGraph",
+        label: "Call Graph Analysis",
+        description: "Enable call graph extraction during analysis. Traces function calls across files to build a dependency graph at the function level.",
+        impact: "Increases analysis time and memory usage. Large codebases may see significant slowdown.",
+        package: "sourcevision",
+        stability: "experimental",
+        defaultValue: false,
+    },
+    {
+        key: "sourcevision.enrichment",
+        label: "AI Enrichment Passes",
+        description: "Enable AI-powered enrichment that adds architectural insights, problem detection, and improvement suggestions to the analysis.",
+        impact: "Requires an API key or CLI access. Each enrichment pass uses token budget.",
+        package: "sourcevision",
+        stability: "stable",
+        defaultValue: true,
+    },
+    {
+        key: "sourcevision.componentCatalog",
+        label: "React Component Catalog",
+        description: "Extract React/Preact component metadata including props, hooks usage, and component hierarchy.",
+        impact: "Only useful for React/Preact projects. Adds a small amount of analysis time.",
+        package: "sourcevision",
+        stability: "stable",
+        defaultValue: true,
+    },
+    // ── Rex ────────────────────────────────────────────────────────────
+    {
+        key: "rex.autoComplete",
+        label: "Auto-Complete Parent Items",
+        description: "Automatically mark parent items (features, epics) as complete when all children are done.",
+        impact: "Parent items transition to 'completed' without manual intervention. Disable if you prefer explicit completion.",
+        package: "rex",
+        stability: "stable",
+        defaultValue: true,
+    },
+    {
+        key: "rex.showTokenBudget",
+        label: "Show Token Budget",
+        description: "Display token budget information on Rex task line items and in the detail side panel. When disabled, only non-zero token usage badges are shown.",
+        impact: "Adds budget percentage and remaining capacity indicators to task views. No performance impact.",
+        package: "rex",
+        stability: "stable",
+        defaultValue: false,
+    },
+    {
+        key: "rex.budgetEnforcement",
+        label: "Budget Enforcement",
+        description: "Enforce token and cost budgets during rex analyze operations. When exceeded, operations are blocked or warned.",
+        impact: "When enabled, analysis operations may be interrupted if budget limits are reached.",
+        package: "rex",
+        stability: "stable",
+        defaultValue: false,
+    },
+    {
+        key: "rex.notionSync",
+        label: "Notion Sync",
+        description: "Enable two-way synchronization between the local PRD and a Notion database. Shows the Notion tab in the Rex sidebar.",
+        impact: "Requires Notion integration setup. Sync operations may modify both local and remote data.",
+        package: "rex",
+        stability: "experimental",
+        defaultValue: false,
+    },
+    {
+        key: "rex.integrations",
+        label: "Integrations",
+        description: "Show the Integrations tab in the Rex sidebar for configuring external service connections.",
+        impact: "No performance impact. Hides integration configuration UI when disabled.",
+        package: "rex",
+        stability: "experimental",
+        defaultValue: false,
+    },
+    // ── Hench ─────────────────────────────────────────────────────────
+    {
+        key: "hench.autoRetry",
+        label: "Automatic Retry on Failure",
+        description: "Automatically retry failed task runs with exponential backoff when transient errors occur.",
+        impact: "May consume additional tokens when retrying. Useful for flaky API connections.",
+        package: "hench",
+        stability: "stable",
+        defaultValue: true,
+    },
+    {
+        key: "hench.guardRails",
+        label: "Guard Rails",
+        description: "Enforce security boundaries: blocked file paths, allowed commands, size limits, and timeouts.",
+        impact: "When disabled, the agent has unrestricted file and command access. Keep enabled for safety.",
+        package: "hench",
+        stability: "stable",
+        defaultValue: true,
+    },
+    {
+        key: "hench.adaptiveWorkflow",
+        label: "Adaptive Workflow Adjustment",
+        description: "Allow the agent to dynamically adjust its workflow based on task complexity and past performance.",
+        impact: "May change execution parameters between runs. Provides better results but less predictable behavior.",
+        package: "hench",
+        stability: "experimental",
+        defaultValue: false,
+    },
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const NDX_CONFIG = ".n-dx.json";
+/** Read .n-dx.json, returning empty object on failure. */
+function readNdxConfig(projectDir) {
+    const configPath = join(projectDir, NDX_CONFIG);
+    if (!existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Write .n-dx.json preserving existing content. */
+function writeNdxConfig(projectDir, config) {
+    const configPath = join(projectDir, NDX_CONFIG);
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+/** Get a nested value from an object by dot-separated path. */
+function getByPath(obj, path) {
+    const parts = path.split(".");
+    let current = obj;
+    for (const part of parts) {
+        if (current == null || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/** Set a nested value in an object by dot-separated path. */
+function setByPath(obj, path, value) {
+    const parts = path.split(".");
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (current[part] == null || typeof current[part] !== "object") {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+/** Build toggles list with current values from config. */
+function buildToggles(projectDir) {
+    const config = readNdxConfig(projectDir);
+    const features = (config.features ?? {});
+    return FEATURE_REGISTRY.map((def) => {
+        // Key in features section is relative (e.g., "sourcevision.callGraph")
+        const stored = getByPath(features, def.key);
+        const enabled = typeof stored === "boolean" ? stored : def.defaultValue;
+        return {
+            key: def.key,
+            label: def.label,
+            description: def.description,
+            impact: def.impact,
+            package: def.package,
+            stability: def.stability,
+            enabled,
+            defaultValue: def.defaultValue,
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+const FEATURES_PREFIX = "/api/features";
+export async function handleFeaturesRoute(req, res, ctx) {
+    const url = req.url || "/";
+    const method = req.method || "GET";
+    // GET /api/features — return all toggles with current state
+    if (method === "GET" && url === FEATURES_PREFIX) {
+        const toggles = buildToggles(ctx.projectDir);
+        jsonResponse(res, 200, { toggles });
+        return true;
+    }
+    // PUT /api/features — update one or more toggle values
+    if (method === "PUT" && url === FEATURES_PREFIX) {
+        try {
+            const body = await readBody(req);
+            const parsed = JSON.parse(body);
+            if (!parsed.changes || typeof parsed.changes !== "object") {
+                errorResponse(res, 400, "Request body must include a 'changes' object mapping feature keys to boolean values.");
+                return true;
+            }
+            // Validate all keys exist in registry
+            const validKeys = new Set(FEATURE_REGISTRY.map((d) => d.key));
+            const invalidKeys = Object.keys(parsed.changes).filter((k) => !validKeys.has(k));
+            if (invalidKeys.length > 0) {
+                errorResponse(res, 400, `Unknown feature key(s): ${invalidKeys.join(", ")}`);
+                return true;
+            }
+            // Validate all values are boolean
+            for (const [key, value] of Object.entries(parsed.changes)) {
+                if (typeof value !== "boolean") {
+                    errorResponse(res, 400, `Feature "${key}" value must be a boolean, got ${typeof value}`);
+                    return true;
+                }
+            }
+            // Apply changes to .n-dx.json
+            const config = readNdxConfig(ctx.projectDir);
+            if (!config.features || typeof config.features !== "object") {
+                config.features = {};
+            }
+            const features = config.features;
+            const applied = [];
+            for (const [key, value] of Object.entries(parsed.changes)) {
+                setByPath(features, key, value);
+                applied.push({ key, enabled: value });
+            }
+            writeNdxConfig(ctx.projectDir, config);
+            jsonResponse(res, 200, { applied });
+            return true;
+        }
+        catch (err) {
+            errorResponse(res, 400, err instanceof Error ? err.message : "Invalid request body");
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=routes-features.js.map

package/packages/web/dist/server/routes-features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes-features.js","sourceRoot":"","sources":["../../src/server/routes-features.ts"],"names":[],"mappings":"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"}

package/packages/web/dist/server/routes-hench.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Hench API routes — agent run history, workflow configuration, and templates.
+ *
+ * All endpoints are under /api/hench/.
+ *
+ * GET    /api/hench/runs                  — list runs with summary (newest first, ?limit=N)
+ * GET    /api/hench/runs/:id              — full run detail with transcript
+ * GET    /api/hench/runs/health           — staleness health check for running runs
+ * POST   /api/hench/runs/:id/mark-stuck   — mark a stuck run as failed
+ * GET    /api/hench/task-usage            — incremental per-task token usage aggregation
+ * GET    /api/hench/audit                 — audit info for active tasks (PIDs, resource usage)
+ * GET    /api/hench/metrics              — concurrent execution metrics and resource utilization
+ * GET    /api/hench/metrics/snapshots    — time-series execution metrics snapshots
+ * GET    /api/hench/memory               — system memory, per-process memory, and resource health
+ * GET    /api/hench/memory/history        — per-process memory history (all tracked processes)
+ * GET    /api/hench/memory/history/:taskId — memory history for a specific task
+ * GET    /api/hench/memory/leaks          — leak detection summary for all active processes
+ * GET    /api/hench/concurrency           — concurrent execution count, limits, and queue status
+ * POST   /api/hench/execute/:taskId/terminate — terminate a running task
+ * GET    /api/hench/config                — current workflow configuration with field metadata
+ * PUT    /api/hench/config                — update workflow configuration (partial or full)
+ * GET    /api/hench/templates             — list all workflow templates (built-in + user)
+ * GET    /api/hench/templates/:id         — get template details
+ * POST   /api/hench/templates             — create/update a user-defined template
+ * POST   /api/hench/templates/:id/apply   — apply a template to current config
+ * DELETE /api/hench/templates/:id         — delete a user-defined template
+ * POST   /api/hench/execute               — trigger Hench run for a specific task
+ * GET    /api/hench/execute/status         — get all active execution statuses
+ * GET    /api/hench/execute/status/:taskId — get specific task execution status
+ * GET    /api/hench/throttle              — current throttle state (paused, concurrency override, etc.)
+ * PUT    /api/hench/throttle              — adjust concurrency limit override
+ * POST   /api/hench/throttle/pause        — pause new task executions
+ * POST   /api/hench/throttle/resume       — resume new task executions
+ * POST   /api/hench/throttle/emergency-stop — terminate all running executions immediately
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ServerContext } from "./types.js";
+import type { WebSocketBroadcaster } from "./websocket.js";
+import { IncrementalTaskUsageAggregator } from "./task-usage.js";
+export declare function getAggregator(runsDir: string): IncrementalTaskUsageAggregator;
+/** Handle Hench API requests. Returns true if the request was handled. */
+export declare function handleHenchRoute(req: IncomingMessage, res: ServerResponse, ctx: ServerContext, broadcast?: WebSocketBroadcaster): boolean | Promise<boolean>;
+/** Execution status for a single task run. */
+export interface TaskExecutionStatus {
+    taskId: string;
+    taskTitle: string;
+    runId: string;
+    status: "starting" | "running" | "completed" | "failed";
+    startedAt: string;
+    finishedAt?: string;
+    lastOutput?: string;
+    error?: string;
+    exitCode?: number | null;
+}
+export type HeartbeatStatus = "healthy" | "warning" | "unresponsive" | "unknown";
+/**
+ * Start a periodic heartbeat monitor that scans for unresponsive running tasks
+ * and broadcasts alerts via WebSocket.
+ *
+ * The monitor runs every 30 seconds and broadcasts:
+ * - `hench:heartbeat-alert` when a task transitions to "warning" or "unresponsive"
+ * - `hench:heartbeat-status` with a summary of all running task heartbeats
+ *
+ * Call this once at server startup. The timer is unref'd so it won't prevent
+ * process exit.
+ */
+export declare function startHeartbeatMonitor(runsDir: string, broadcast: WebSocketBroadcaster): void;
+/**
+ * Start a periodic concurrency status broadcaster.
+ *
+ * Broadcasts `hench:concurrency-status` via WebSocket every 10 seconds
+ * with current process count, max limit, utilization level, and queue info.
+ * This enables real-time updates of the concurrency panel in the dashboard.
+ *
+ * Call this once at server startup alongside startHeartbeatMonitor.
+ * The timer is unref'd so it won't prevent process exit.
+ */
+export declare function startConcurrencyMonitor(ctx: ServerContext, broadcast: WebSocketBroadcaster): void;
+/**
+ * Periodically broadcast memory + resource health via WebSocket.
+ * Runs every 10 seconds so the memory panel stays live.
+ *
+ * Also records per-process RSS samples into the process memory tracker
+ * for historical analysis and leak detection.
+ */
+export declare function startMemoryMonitor(broadcast: WebSocketBroadcaster): void;
+/**
+ * Result returned by {@link shutdownActiveExecutions}.
+ *
+ * Callers (e.g. `gracefulShutdown` in start.ts) use these counts to
+ * build a final verification summary and to decide whether to exit clean.
+ */
+export interface ShutdownExecutionsResult {
+    /** Number of executions that were cleanly terminated. */
+    terminated: number;
+    /** Number of executions that failed to terminate (kill errored or timed out). */
+    failed: number;
+}
+/**
+ * Gracefully terminate all active hench executions on server shutdown.
+ *
+ * Iterates over all entries in `activeExecutions`, sends SIGTERM to each
+ * managed child, and waits up to `gracePeriodMs` for them to exit.  Any
+ * process that does not exit within the grace period receives SIGKILL.
+ *
+ * This must be called before the HTTP server closes so that child processes
+ * are not orphaned.  The function resolves only after all processes have
+ * been signalled and (best-effort) waited for.
+ *
+ * @param gracePeriodMs  How long to wait for each process to exit gracefully
+ *                       before force-killing it.  Defaults to 5 000 ms.
+ *                       Can be overridden via the `HENCH_SHUTDOWN_TIMEOUT_MS`
+ *                       environment variable.
+ * @returns Counts of terminated and failed executions for verification.
+ */
+export declare function shutdownActiveExecutions(gracePeriodMs?: number): Promise<ShutdownExecutionsResult>;