jfl 0.2.5 → 0.3.0

package/README.md

@@ -63,6 +63,8 @@ my-project/                    <- GTM workspace (strategy, context, orchestratio
 │   ├── config.json           <- Project config (team, services, ports)
 │   ├── journal/              <- Session journals (JSONL, one file per session)
 │   ├── memory.db             <- Indexed memory (TF-IDF + embeddings)
+│   ├── agents/              <- Narrowly-scoped agent manifests + policies
+│   ├── flows/               <- Per-agent flow definitions (auto-loaded)
 │   ├── service-events.jsonl  <- Event bus file-drop
 │   └── services.json         <- Registered services
 ├── knowledge/                <- Strategy docs (VISION, ROADMAP, THESIS, etc.)
@@ -233,6 +235,7 @@ jfl services                  # Interactive TUI (no args)
 | `jfl init -n <name>` | Create new GTM workspace |
 | `jfl status` | Project status and auth |
 | `jfl hud [-c\|--compact]` | Campaign dashboard (ship date, phases, pipeline) |
+| `jfl doctor [--fix]` | Check project health, auto-repair fixable issues |
 | `jfl update [--dry]` | Pull latest skills, scripts, templates (preserves CLAUDE.md, .mcp.json) |
 | `jfl synopsis [hours] [author]` | Work summary (journal + commits + file headers) |
 | `jfl repair` | Fix corrupted .jfl/config.json |
@@ -290,6 +293,9 @@ jfl services                  # Interactive TUI (no args)
 
 | Command | Description |
 |---------|-------------|
+| `jfl agent init <name> [-d desc]` | Scaffold agent (manifest + policy + lifecycle flows) |
+| `jfl agent list` | List registered agents |
+| `jfl agent status <name>` | Show agent health and config |
 | `jfl ralph [args]` | Ralph-tui agent loop orchestrator |
 | `jfl peter [action]` | Peter Parker model-routed orchestrator (setup, run, status) |
 | `jfl orchestrate [name] [--list] [--create <n>]` | Multi-service orchestration workflows |
@@ -524,6 +530,16 @@ jfl wallet                    # Wallet and day pass status
 
 ## What's New
 
+**0.2.5**
+- Feat: Docker-style grouped `jfl --help` — 5 groups (Getting Started, Daily Use, Management, Platform, Advanced), ~30 lines down from 52
+- Feat: `jfl doctor [--fix]` — unified project health checker (9 checks: .jfl dir, config, Context Hub, hooks, memory, journal, agents, flows, git). Auto-repairs hooks, config, and journal with `--fix`
+- Feat: `jfl agent init|list|status` — scaffold narrowly-scoped agents with manifest, policy, and lifecycle flows
+- Feat: Flow engine scans `.jfl/flows/*.yaml` for per-agent flow definitions
+- Feat: Kuva terminal plots + spawn action type in flow engine
+- Fix: Stop committing JFL runtime files (.jfl/logs/, memory.db, *.pid) — gitignore + untrack ([@hathbanger](https://github.com/hathbanger) [#5](https://github.com/402goose/jfl-cli/pull/5))
+- Fix: Enforce `jfl update --auto` on session start with 24h cache ([@hathbanger](https://github.com/hathbanger) [#5](https://github.com/402goose/jfl-cli/pull/5))
+- Test: 31 new tests (agent-manifest, doctor, agent command, flow-engine directory scan)
+
 **0.2.4**
 - Feat: `jfl telemetry digest` — per-model cost tables, command stats, health analysis, improvement suggestions
 - Feat: `jfl improve` — self-improvement loop with GitHub issue creation (`--auto`)

package/dist/commands/context-hub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-hub.d.ts","sourceRoot":"","sources":["../../src/commands/context-hub.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoiCH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAiBjF;AA2ND,wBAAsB,qBAAqB,CAAC,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAiHxF;AAMD,wBAAsB,iBAAiB,CACrC,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,iBAwenE"}
+{"version":3,"file":"context-hub.d.ts","sourceRoot":"","sources":["../../src/commands/context-hub.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmzCH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAiBjF;AA2ND,wBAAsB,qBAAqB,CAAC,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAiHxF;AAMD,wBAAsB,iBAAiB,CACrC,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,iBA8enE"}

package/dist/commands/context-hub.js

@@ -415,11 +415,89 @@ function getUnifiedContext(projectRoot, query, taskType) {
         taskType
     };
 }
+function getChildHubs(projectRoot) {
+    const configPath = path.join(projectRoot, ".jfl", "config.json");
+    if (!fs.existsSync(configPath))
+        return [];
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        if (config.type !== "portfolio")
+            return [];
+        const children = [];
+        for (const service of config.registered_services || []) {
+            if (service.type === "gtm" && service.path) {
+                const childPort = getProjectPort(service.path);
+                const tokenPath = path.join(service.path, ".jfl", "context-hub.token");
+                const token = fs.existsSync(tokenPath)
+                    ? fs.readFileSync(tokenPath, "utf-8").trim()
+                    : undefined;
+                children.push({ name: service.name, path: service.path, port: childPort, token });
+            }
+        }
+        return children;
+    }
+    catch {
+        return [];
+    }
+}
+async function fetchChildContext(child, endpoint, body) {
+    try {
+        const headers = { "Content-Type": "application/json" };
+        if (child.token)
+            headers["Authorization"] = `Bearer ${child.token}`;
+        const response = await fetch(`http://localhost:${child.port}${endpoint}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok)
+            return [];
+        const data = (await response.json());
+        return (data.items || []).map((item) => ({
+            ...item,
+            title: `[${child.name}] ${item.title}`,
+        }));
+    }
+    catch {
+        return readJournalEntries(child.path, 10).map((item) => ({
+            ...item,
+            title: `[${child.name}] ${item.title}`,
+        }));
+    }
+}
+async function getPortfolioContext(projectRoot, query, taskType, maxItems) {
+    const local = getUnifiedContext(projectRoot, query, taskType);
+    const children = getChildHubs(projectRoot);
+    if (children.length === 0)
+        return local;
+    const endpoint = query ? "/api/context/search" : "/api/context";
+    const body = { maxItems: maxItems || 20 };
+    if (query)
+        body.query = query;
+    if (taskType)
+        body.taskType = taskType;
+    const childResults = await Promise.all(children.map((child) => fetchChildContext(child, endpoint, body)));
+    let merged = [...local.items, ...childResults.flat()];
+    if (query) {
+        merged = semanticSearch(merged, query);
+    }
+    return {
+        items: maxItems ? merged.slice(0, maxItems) : merged,
+        sources: {
+            ...local.sources,
+            journal: true,
+            knowledge: true,
+        },
+        query,
+        taskType,
+    };
+}
 // ============================================================================
 // HTTP Server
 // ============================================================================
-function createServer(projectRoot, port, eventBus) {
-    const server = http.createServer((req, res) => {
+function createServer(projectRoot, port, eventBus, flowEngine) {
+    const server = http.createServer(async (req, res) => {
         const requestStart = Date.now();
         const pathname = new URL(req.url || "/", `http://localhost:${port}`).pathname;
         // Intercept writeHead to capture status code for telemetry
@@ -533,29 +611,68 @@ function createServer(projectRoot, port, eventBus) {
             }));
             return;
         }
-        // Status
+        // Status (includes child hub health for portfolio)
         if (url.pathname === "/api/context/status" && req.method === "GET") {
             const context = getUnifiedContext(projectRoot);
+            const children = getChildHubs(projectRoot);
+            // Read actual workspace type from config
+            let workspaceType = "standalone";
+            let workspaceConfig = {};
+            const configPath = path.join(projectRoot, ".jfl", "config.json");
+            if (fs.existsSync(configPath)) {
+                try {
+                    const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+                    if (cfg.type === "portfolio" || cfg.type === "gtm" || cfg.type === "service") {
+                        workspaceType = cfg.type;
+                    }
+                    workspaceConfig = {
+                        name: cfg.name,
+                        type: cfg.type,
+                        description: cfg.description,
+                        scope: cfg.context_scope || null,
+                        registered_services: (cfg.registered_services || []).map((s) => ({
+                            name: s.name,
+                            type: s.type,
+                            status: s.status,
+                            context_scope: s.context_scope || null,
+                        })),
+                        gtm_parent: cfg.gtm_parent || null,
+                        portfolio_parent: cfg.portfolio_parent || null,
+                    };
+                }
+                catch { }
+            }
+            const childStatus = await Promise.all(children.map(async (child) => {
+                try {
+                    const resp = await fetch(`http://localhost:${child.port}/health`, {
+                        signal: AbortSignal.timeout(2000),
+                    });
+                    return { name: child.name, port: child.port, status: resp.ok ? "ok" : "error" };
+                }
+                catch {
+                    return { name: child.name, port: child.port, status: "down" };
+                }
+            }));
             res.writeHead(200, { "Content-Type": "application/json" });
             res.end(JSON.stringify({
                 status: "running",
                 port,
+                type: workspaceType,
+                config: workspaceConfig,
                 sources: context.sources,
-                itemCount: context.items.length
+                itemCount: context.items.length,
+                ...(children.length > 0 ? { children: childStatus } : {}),
             }));
             return;
         }
-        // Get context
+        // Get context (portfolio-aware: fans out to child hubs)
         if (url.pathname === "/api/context" && req.method === "POST") {
             let body = "";
             req.on("data", chunk => body += chunk);
-            req.on("end", () => {
+            req.on("end", async () => {
                 try {
                     const { query, taskType, maxItems } = JSON.parse(body || "{}");
-                    const context = getUnifiedContext(projectRoot, query, taskType);
-                    if (maxItems && context.items.length > maxItems) {
-                        context.items = context.items.slice(0, maxItems);
-                    }
+                    const context = await getPortfolioContext(projectRoot, query, taskType, maxItems);
                     telemetry.track({
                         category: 'context_hub',
                         event: 'context_hub:context_loaded',
@@ -575,11 +692,11 @@ function createServer(projectRoot, port, eventBus) {
             });
             return;
         }
-        // Search
+        // Search (portfolio-aware: fans out to child hubs)
         if (url.pathname === "/api/context/search" && req.method === "POST") {
             let body = "";
             req.on("data", chunk => body += chunk);
-            req.on("end", () => {
+            req.on("end", async () => {
                 try {
                     const { query, maxItems = 20 } = JSON.parse(body || "{}");
                     if (!query) {
@@ -588,7 +705,7 @@ function createServer(projectRoot, port, eventBus) {
                         return;
                     }
                     const searchStart = Date.now();
-                    const context = getUnifiedContext(projectRoot, query);
+                    const context = await getPortfolioContext(projectRoot, query, undefined, maxItems);
                     context.items = context.items
                         .filter(item => item.relevance && item.relevance > 0)
                         .slice(0, maxItems);
@@ -707,6 +824,58 @@ function createServer(projectRoot, port, eventBus) {
             });
             return;
         }
+        // Eval trajectory
+        if (url.pathname === "/api/eval/trajectory" && req.method === "GET") {
+            try {
+                const { getTrajectory } = await import("../lib/eval-store.js");
+                const agent = url.searchParams.get("agent") || "";
+                const metric = url.searchParams.get("metric") || "composite";
+                if (!agent) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "agent query param required" }));
+                    return;
+                }
+                const points = getTrajectory(agent, metric, projectRoot);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ agent, metric, points }));
+            }
+            catch (err) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: err.message }));
+            }
+            return;
+        }
+        // Eval leaderboard
+        if (url.pathname === "/api/eval/leaderboard" && req.method === "GET") {
+            try {
+                const { readEvals, listAgents, getLatestEval, getTrajectory } = await import("../lib/eval-store.js");
+                const agents = listAgents(projectRoot);
+                const leaderboard = agents.map(agent => {
+                    const latest = getLatestEval(agent, projectRoot);
+                    const trajectory = getTrajectory(agent, "composite", projectRoot);
+                    const prevPoint = trajectory.length >= 2 ? trajectory[trajectory.length - 2] : null;
+                    const delta = latest?.composite != null && prevPoint
+                        ? latest.composite - prevPoint.value
+                        : null;
+                    return {
+                        agent,
+                        composite: latest?.composite ?? null,
+                        metrics: latest?.metrics ?? {},
+                        delta,
+                        model_version: latest?.model_version ?? null,
+                        lastTs: latest?.ts ?? null,
+                        trajectory: trajectory.slice(-20).map(p => p.value),
+                    };
+                }).sort((a, b) => (b.composite ?? 0) - (a.composite ?? 0));
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(leaderboard));
+            }
+            catch (err) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: err.message }));
+            }
+            return;
+        }
         // Cross-project health
         if (url.pathname === "/api/projects" && req.method === "GET") {
             const tracked = getTrackedProjects();
@@ -820,6 +989,78 @@ function createServer(projectRoot, port, eventBus) {
             });
             return;
         }
+        // Telemetry digest
+        if (url.pathname === "/api/telemetry/digest" && req.method === "GET") {
+            try {
+                const { loadLocalEvents, analyzeEvents } = await import("../lib/telemetry-digest.js");
+                const hours = parseInt(url.searchParams.get("hours") || "168", 10);
+                const events = loadLocalEvents();
+                const digest = analyzeEvents(events, hours);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(digest));
+            }
+            catch (err) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: err.message }));
+            }
+            return;
+        }
+        // Flow definitions
+        if (url.pathname === "/api/flows" && req.method === "GET") {
+            if (!flowEngine) {
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify([]));
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(flowEngine.getFlows()));
+            return;
+        }
+        // Flow executions
+        if (url.pathname === "/api/flows/executions" && req.method === "GET") {
+            if (!flowEngine) {
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ executions: [] }));
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ executions: flowEngine.getExecutions() }));
+            return;
+        }
+        // Flow approval
+        if (url.pathname.match(/^\/api\/flows\/[^/]+\/approve$/) && req.method === "POST") {
+            if (!flowEngine) {
+                res.writeHead(503, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Flow engine not initialized" }));
+                return;
+            }
+            const flowName = decodeURIComponent(url.pathname.split("/")[3]);
+            let body = "";
+            req.on("data", chunk => body += chunk);
+            req.on("end", async () => {
+                try {
+                    const { trigger_event_id } = JSON.parse(body || "{}");
+                    if (!trigger_event_id) {
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "trigger_event_id required" }));
+                        return;
+                    }
+                    const result = await flowEngine.approveGated(flowName, trigger_event_id);
+                    if (!result) {
+                        res.writeHead(404, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "Gated execution not found" }));
+                        return;
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(result));
+                }
+                catch (err) {
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: err.message }));
+                }
+            });
+            return;
+        }
         // 404
         res.writeHead(404, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: "Not found" }));
@@ -1187,17 +1428,18 @@ export async function contextHubCommand(action, options = {}) {
     const isGlobal = options.global || false;
     const projectRoot = isGlobal ? homedir() : process.cwd();
     const port = options.port || getProjectPort(projectRoot);
-    // Ensure directories exist
-    if (isGlobal) {
-        // Global mode: use XDG directories
-        const { JFL_PATHS, ensureJflDirs } = await import("../utils/jfl-paths.js");
-        ensureJflDirs();
-    }
-    else {
-        // Project mode: use .jfl/
-        const jflDir = path.join(projectRoot, ".jfl");
-        if (!fs.existsSync(jflDir)) {
-            fs.mkdirSync(jflDir, { recursive: true });
+    // Ensure directories exist (skip for actions that don't need local project root)
+    const globalActions = ["ensure-all", "doctor", "install-daemon", "uninstall-daemon"];
+    if (!globalActions.includes(action || "")) {
+        if (isGlobal) {
+            const { JFL_PATHS, ensureJflDirs } = await import("../utils/jfl-paths.js");
+            ensureJflDirs();
+        }
+        else {
+            const jflDir = path.join(projectRoot, ".jfl");
+            if (!fs.existsSync(jflDir)) {
+                fs.mkdirSync(jflDir, { recursive: true });
+            }
         }
     }
     switch (action) {
@@ -1397,7 +1639,8 @@ export async function contextHubCommand(action, options = {}) {
                 serviceEventsPath,
                 journalDir: fs.existsSync(journalDir) ? journalDir : null,
             });
-            const server = createServer(projectRoot, port, eventBus);
+            const flowEngine = new FlowEngine(eventBus, projectRoot);
+            const server = createServer(projectRoot, port, eventBus, flowEngine);
             let isListening = false;
             // When spawned as daemon, ignore SIGTERM during startup grace period.
             // The parent process (hook runner) may exit and send SIGTERM to the
@@ -1470,9 +1713,13 @@ export async function contextHubCommand(action, options = {}) {
                     console.error(`[${timestamp}] Failed to initialize memory system:`, err.message);
                     // Don't exit - memory is optional
                 }
-                // Start flow engine
+                // Start flow engine (with child hub connections for portfolio mode)
                 try {
-                    const flowEngine = new FlowEngine(eventBus, projectRoot);
+                    const children = getChildHubs(projectRoot);
+                    if (children.length > 0) {
+                        flowEngine.setChildren(children);
+                        console.log(`[${timestamp}] Portfolio mode: connecting to ${children.length} child hub(s)`);
+                    }
                     const flowCount = await flowEngine.start();
                     if (flowCount > 0) {
                         console.log(`[${timestamp}] Flow engine started with ${flowCount} active flow(s)`);