@agentic-surfaces/cli 0.1.29 → 0.1.30

package/dist/index.js

@@ -1,7 +1,7 @@
-import { readFileSync, readdirSync, existsSync } from "node:fs";
-import { join, dirname, resolve } from "node:path";
+import { readFileSync, readdirSync, existsSync, watch as watchFs, } from "node:fs";
+import { join, dirname, resolve, relative, sep } from "node:path";
 import { spawn } from "node:child_process";
-import { loadWorkflow, runWorkflowOnce, Scheduler, loadProjectConfig, buildWorkflowRunner, defaultRegistry, parseAgentFile, FilePauseState } from "@agentic-surfaces/core";
+import { loadWorkflow, runWorkflowOnce, Scheduler, loadProjectConfig, buildWorkflowRunner, defaultRegistry, parseAgentFile, FilePauseState, } from "@agentic-surfaces/core";
 import { serve, StreamingObserver } from "@agentic-surfaces/server";
 import { buildServices } from "./services.js";
 const CONFIG = "agentic-surfaces.config.yaml";
@@ -19,7 +19,8 @@ function loadDotenv(dir = process.cwd()) {
         if (!m)
             continue; // skips blanks + `# comments`
         let val = m[2];
-        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))
+        if ((val.startsWith('"') && val.endsWith('"')) ||
+            (val.startsWith("'") && val.endsWith("'")))
             val = val.slice(1, -1);
         if (process.env[m[1]] === undefined)
             process.env[m[1]] = val;
@@ -41,15 +42,63 @@ function discoverProjectDir(start) {
         dir = parent;
     }
 }
-// Load every workflow yaml in a folder into a name→Workflow map.
+// Recursively collect every workflow yaml under `dir` as absolute file paths.
+// Subdirectories are walked so workflows can be organised into folders (the
+// folder path becomes the sidebar group when a workflow omits an explicit
+// `group:` field — see loadWorkflows).
+function collectWorkflowFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...collectWorkflowFiles(full));
+        }
+        else if (entry.isFile() &&
+            entry.name.endsWith(".yaml") &&
+            entry.name !== CONFIG) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+// Derive the fallback group for a workflow file from its subdirectory path
+// relative to the workflows dir. `workflows/sentry/poll.yaml` → "sentry";
+// `workflows/sentry/bugs/x.yaml` → "sentry/bugs"; a file at the root → undefined.
+function groupFromPath(rootDir, file) {
+    const rel = relative(rootDir, dirname(file));
+    if (!rel || rel === "." || rel.startsWith(".."))
+        return undefined;
+    return rel.split(sep).join("/");
+}
+// Load every workflow yaml under a folder (recursively) into a name→Workflow map.
+// Grouping precedence: an explicit top-level `group:` field on the workflow wins;
+// otherwise the file's subdirectory path becomes the group; a workflow at the root
+// with no `group:` stays ungrouped. The map is keyed by workflow `name`, which must
+// stay globally unique across subdirs (sub-workflow `foreach`/run-workflow refs
+// resolve by name) — a collision is a hard error rather than a silent overwrite.
 function loadWorkflows(dir) {
     const map = new Map();
-    for (const f of readdirSync(dir).filter((f) => f.endsWith(".yaml") && f !== CONFIG)) {
+    const seenAt = new Map(); // name → file that defined it
+    for (const file of collectWorkflowFiles(dir)) {
+        let w;
         try {
-            const w = loadWorkflow(readFileSync(join(dir, f), "utf8"));
-            map.set(w.name, w);
+            w = loadWorkflow(readFileSync(file, "utf8"));
+        }
+        catch {
+            continue; /* skip unparseable */
         }
-        catch { /* skip unparseable */ }
+        if (seenAt.has(w.name)) {
+            throw new Error(`duplicate workflow name "${w.name}" — defined in both ${relative(dir, seenAt.get(w.name))} and ${relative(dir, file)}. ` +
+                `Workflow names must be globally unique (they are how sub-workflows are referenced).`);
+        }
+        seenAt.set(w.name, file);
+        // Explicit `group:` field wins; otherwise fall back to the subdirectory path.
+        if (w.group === undefined) {
+            const g = groupFromPath(dir, file);
+            if (g)
+                w = { ...w, group: g };
+        }
+        map.set(w.name, w);
     }
     return map;
 }
@@ -71,6 +120,74 @@ function loadAgents(projectDir) {
     }
     return map;
 }
+/**
+ * Build the in-process hot-reload function for `start`/`ui`. Re-scans the workflows dir (recursively,
+ * same loader as startup) + the agents dir, rebuilds the shared maps IN PLACE (so the workflow runner's
+ * closure over `workflows` and `services.agents` sees the new set), and re-registers the scheduler's cron
+ * timers from the fresh workflow set. Returns the new workflow list for the server to serve.
+ *
+ * Mutating the existing Map instances (rather than replacing them) is deliberate: the runner built by
+ * `buildWorkflowRunner` and the services object both close over those Map references, so `foreach` /
+ * run-workflow sub-workflow resolution and agent lookups pick up edits without rebuilding the runner.
+ *
+ * A reload that fails to parse the dir (e.g. mid-write) is reported and skipped — the previous good set
+ * stays live rather than blanking the dashboard.
+ */
+function makeReloader(opts) {
+    return () => {
+        const next = loadWorkflows(opts.workflowsDir); // throws on duplicate names; caught by /api/reload
+        // Rebuild the shared workflow map in place.
+        opts.workflows.clear();
+        for (const [name, wf] of next)
+            opts.workflows.set(name, wf);
+        // Rebuild the shared agents map in place.
+        const nextAgents = loadAgents(opts.projectDir);
+        opts.agents.clear();
+        for (const [name, def] of nextAgents)
+            opts.agents.set(name, def);
+        // Re-register cron timers from the fresh set (cancels the old ones — no leaks, no double-fire).
+        opts.scheduler.reload([...next.values()]);
+        return [...next.values()];
+    };
+}
+/**
+ * Watch the project dir (recursively) and hot-reload on workflow/agent edits. Editors fire several
+ * fs events per save, so the reload is debounced (~400ms). After a successful reload it emits a
+ * `workflows:changed` SSE event so the dashboard re-fetches /api/workflows without a refresh.
+ *
+ * Loop guard: a reload only reads files (the scheduler + maps are rebuilt from them) and never writes
+ * back into the watched dir, so a reload cannot retrigger itself; the debounce additionally collapses
+ * any burst into a single reload.
+ *
+ * This is the in-process successor to the old `--watch` (which exited for a supervisor restart). The
+ * launchd path that relied on `start --watch` still works — see the `start` command for the flag's
+ * retained behavior.
+ */
+function watchAndReload(dir, observer, reload) {
+    let pending;
+    try {
+        watchFs(dir, { recursive: true }, (_event, filename) => {
+            if (!filename || !/\.(yaml|md)$/.test(filename.toString()))
+                return;
+            clearTimeout(pending);
+            pending = setTimeout(() => {
+                try {
+                    const next = reload();
+                    observer.notifyWorkflowsChanged();
+                    console.log(`hot-reload: ${next.length} workflow(s) (changed: ${filename})`);
+                }
+                catch (err) {
+                    // Keep the previous good set live; just report (e.g. mid-write parse error or a name clash).
+                    console.error("hot-reload skipped:", err instanceof Error ? err.message : String(err));
+                }
+            }, 400); // debounce editor multi-writes
+        });
+    }
+    catch (err) {
+        // recursive watch isn't supported everywhere; degrade to manual reload (the Reload button).
+        console.error("hot-reload watch unavailable (use the Reload button):", err instanceof Error ? err.message : String(err));
+    }
+}
 // Walk up to the directory that contains agentic-surfaces.config.yaml.
 function findProjectDir(start) {
     let dir = resolve(start);
@@ -107,7 +224,13 @@ function launchUi(opts) {
         cache: opts.cache,
         pause: opts.pause,
         planUsage: opts.planUsage,
-        config: { dryRun: opts.dryRun, agent: opts.agentDefaults, version: VERSION, atlassianSite: opts.atlassianSite },
+        onReload: opts.onReload,
+        config: {
+            dryRun: opts.dryRun,
+            agent: opts.agentDefaults,
+            version: VERSION,
+            atlassianSite: opts.atlassianSite,
+        },
     });
     const url = `http://127.0.0.1:${p}`;
     openBrowser(url);
@@ -116,8 +239,10 @@ function launchUi(opts) {
 function openBrowser(url) {
     if (process.env["FLOW_NO_OPEN"])
         return; // headless / CI / don't hijack a browser
-    const cmd = process.platform === "darwin" ? "open"
-        : process.platform === "win32" ? "start"
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "start"
             : "xdg-open";
     try {
         spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
@@ -164,8 +289,17 @@ export async function run(argv) {
             const registry = defaultRegistry();
             const observer = new StreamingObserver();
             const services = buildServices({ projectConfig: pc, projectDir: dir });
-            const runWorkflowFn = buildWorkflowRunner({ workflows: allWorkflows, registry, services: { ...services, agents }, observer });
-            const servicesWithRunner = { ...services, agents, runWorkflow: runWorkflowFn };
+            const runWorkflowFn = buildWorkflowRunner({
+                workflows: allWorkflows,
+                registry,
+                services: { ...services, agents },
+                observer,
+            });
+            const servicesWithRunner = {
+                ...services,
+                agents,
+                runWorkflow: runWorkflowFn,
+            };
             // Platform-wide play/pause (file-backed so it survives a --watch restart).
             const pause = new FilePauseState();
             // Cron-triggered workflows fire on schedule too.
@@ -173,8 +307,17 @@ export async function run(argv) {
             for (const [, w] of allWorkflows)
                 sched.add(w);
             sched.start();
+            const reload = makeReloader({
+                workflowsDir,
+                projectDir: dir,
+                workflows: allWorkflows,
+                agents,
+                scheduler: sched,
+            });
             const url = launchUi({
-                observer, workflows: allWorkflows, agents,
+                observer,
+                workflows: allWorkflows,
+                agents,
                 onRun: (name, payload) => runWorkflowFn(name, payload),
                 cache: services.cache,
                 pause,
@@ -182,9 +325,13 @@ export async function run(argv) {
                 dryRun: pc?.dryRun,
                 agentDefaults: { model: pc?.agent?.model, effort: pc?.agent?.effort },
                 atlassianSite: pc?.atlassianSite,
+                onReload: reload,
             });
+            // Automatic hot reload: a debounced recursive watch on the project dir re-scans + re-registers
+            // the scheduler in place and pushes a `workflows:changed` SSE event so the dashboard re-fetches.
+            watchAndReload(dir, observer, reload);
             console.log(`\n▶ agentic-surfaces ${VERSION} — ${url}`);
-            console.log(`  project: ${dir}  ·  ${allWorkflows.size} workflow(s)  ·  Ctrl-C to exit`);
+            console.log(`  project: ${dir}  ·  ${allWorkflows.size} workflow(s)  ·  hot-reload on  ·  Ctrl-C to exit`);
             await new Promise(() => { }); // serve until interrupted
             return 0;
         }
@@ -194,7 +341,7 @@ export async function run(argv) {
             return 0;
         }
         if (cmd === "run-once" || cmd === "run") {
-            const file = rest.find(a => !a.startsWith("--"));
+            const file = rest.find((a) => !a.startsWith("--"));
             if (!file) {
                 console.error("run: missing workflow file");
                 return 1;
@@ -203,36 +350,60 @@ export async function run(argv) {
             const pc = findProjectConfig(dirname(file));
             const wf = loadWorkflow(readFileSync(file, "utf8"));
             const projectDir = findProjectDir(dirname(file)) ?? dirname(file);
-            const services = buildServices(fake ? { fakeAgent: [{ text: "fake reply" }], projectConfig: pc, projectDir } : { projectConfig: pc, projectDir });
-            const dir = dirname(file);
-            const allWorkflows = new Map();
-            for (const f of readdirSync(dir).filter(f => f.endsWith(".yaml") && f !== "agentic-surfaces.config.yaml")) {
-                try {
-                    const w = loadWorkflow(readFileSync(join(dir, f), "utf8"));
-                    allWorkflows.set(w.name, w);
+            const services = buildServices(fake
+                ? {
+                    fakeAgent: [{ text: "fake reply" }],
+                    projectConfig: pc,
+                    projectDir,
                 }
-                catch { /* skip unparseable */ }
-            }
+                : { projectConfig: pc, projectDir });
+            // Scan recursively from the workflows root (so sub-workflow refs resolve
+            // across subdir folders + groups come through), falling back to the file's
+            // own dir when no project config is present.
+            const scanDir = pc?.workflows
+                ? join(projectDir, pc.workflows)
+                : dirname(file);
+            const allWorkflows = loadWorkflows(scanDir);
             const agents = loadAgents(projectDir);
             const registry = defaultRegistry();
             const ui = rest.includes("--ui");
             const observer = ui ? new StreamingObserver() : undefined;
-            const runWorkflowFn = buildWorkflowRunner({ workflows: allWorkflows, registry, services: { ...services, agents }, observer });
-            const servicesWithRunner = { ...services, agents, runWorkflow: runWorkflowFn };
-            const url = ui ? launchUi({
-                observer: observer, workflows: allWorkflows, agents,
-                onRun: (name, payload) => runWorkflowFn(name, payload),
-                cache: services.cache,
-                dryRun: pc?.dryRun,
-                agentDefaults: { model: pc?.agent?.model, effort: pc?.agent?.effort },
-                atlassianSite: pc?.atlassianSite,
-            }) : undefined;
+            const runWorkflowFn = buildWorkflowRunner({
+                workflows: allWorkflows,
+                registry,
+                services: { ...services, agents },
+                observer,
+            });
+            const servicesWithRunner = {
+                ...services,
+                agents,
+                runWorkflow: runWorkflowFn,
+            };
+            const url = ui
+                ? launchUi({
+                    observer: observer,
+                    workflows: allWorkflows,
+                    agents,
+                    onRun: (name, payload) => runWorkflowFn(name, payload),
+                    cache: services.cache,
+                    dryRun: pc?.dryRun,
+                    agentDefaults: {
+                        model: pc?.agent?.model,
+                        effort: pc?.agent?.effort,
+                    },
+                    atlassianSite: pc?.atlassianSite,
+                })
+                : undefined;
             // A run error must NOT tear down the --ui server: the failure is already
             // streamed to the dashboard (the failed node + run), so keep serving so it
             // stays inspectable. Without --ui, an error still exits non-zero.
             let failed = false;
             try {
-                const outputs = await runWorkflowOnce(wf, { registry, services: servicesWithRunner, observer });
+                const outputs = await runWorkflowOnce(wf, {
+                    registry,
+                    services: servicesWithRunner,
+                    observer,
+                });
                 console.log("ran", wf.name, "->", [...outputs.keys()].join(", "));
             }
             catch (err) {
@@ -246,34 +417,45 @@ export async function run(argv) {
             return failed ? 1 : 0;
         }
         if (cmd === "start") {
-            const dir = rest.find(a => !a.startsWith("--")) ?? ".";
+            const dir = rest.find((a) => !a.startsWith("--")) ?? ".";
             const pc = loadProjectConfig(dir);
             const workflowsDir = pc?.workflows ? join(dir, pc.workflows) : dir;
             const services = buildServices({ projectConfig: pc, projectDir: dir });
-            const allWorkflows = new Map();
-            const yamlFiles = readdirSync(workflowsDir).filter(f => f.endsWith(".yaml") && f !== "agentic-surfaces.config.yaml");
-            for (const f of yamlFiles) {
-                try {
-                    const w = loadWorkflow(readFileSync(join(workflowsDir, f), "utf8"));
-                    allWorkflows.set(w.name, w);
-                }
-                catch { /* skip unparseable */ }
-            }
+            const allWorkflows = loadWorkflows(workflowsDir);
             const agents = loadAgents(dir);
             const registry = defaultRegistry();
             const ui = rest.includes("--ui");
             const observer = ui ? new StreamingObserver() : undefined;
-            const runWorkflowFn = buildWorkflowRunner({ workflows: allWorkflows, registry, services: { ...services, agents }, observer });
-            const servicesWithRunner = { ...services, agents, runWorkflow: runWorkflowFn };
+            const runWorkflowFn = buildWorkflowRunner({
+                workflows: allWorkflows,
+                registry,
+                services: { ...services, agents },
+                observer,
+            });
+            const servicesWithRunner = {
+                ...services,
+                agents,
+                runWorkflow: runWorkflowFn,
+            };
             const pause = new FilePauseState();
             const sched = new Scheduler(servicesWithRunner, registry, observer, pause);
             for (const [, w] of allWorkflows)
                 sched.add(w);
             sched.start();
+            const reload = makeReloader({
+                workflowsDir,
+                projectDir: dir,
+                workflows: allWorkflows,
+                agents,
+                scheduler: sched,
+            });
             console.log(`scheduler started; watching ${workflowsDir}${pause.isPaused() ? "  (PAUSED)" : ""}`);
+            const watchFlag = rest.includes("--watch");
             if (ui) {
                 const url = launchUi({
-                    observer: observer, workflows: allWorkflows, agents,
+                    observer: observer,
+                    workflows: allWorkflows,
+                    agents,
                     onRun: (name, payload) => runWorkflowFn(name, payload),
                     cache: services.cache,
                     pause,
@@ -281,13 +463,22 @@ export async function run(argv) {
                     dryRun: pc?.dryRun,
                     agentDefaults: { model: pc?.agent?.model, effort: pc?.agent?.effort },
                     atlassianSite: pc?.atlassianSite,
+                    onReload: reload,
                 });
                 console.log(`▶ agentic-surfaces ${VERSION} — ${url}`);
+                // With the dashboard up, prefer in-process hot reload (button + automatic) over the legacy
+                // process-exit watcher — unless --watch is explicitly passed (the supervisor-restart contract).
+                if (!watchFlag) {
+                    watchAndReload(dir, observer, reload);
+                    console.log("hot-reload on (Reload button + automatic file watch)");
+                }
             }
             // --watch: exit when a config file changes so a supervisor (launchd/pm2/systemd) restarts us
             // with the fresh config. The seen-cache (.flow-cache.sqlite) persists across the restart, so
-            // dedup is preserved. Without a supervisor this just exits on the first edit.
-            if (rest.includes("--watch")) {
+            // dedup is preserved. Without a supervisor this just exits on the first edit. RETAINED for the
+            // launchd path; the dashboard's in-process hot reload above is the lighter-weight default when
+            // --watch is omitted. When --watch is set it wins (a supervisor expects the process to exit).
+            if (watchFlag) {
                 const { watch } = await import("node:fs");
                 let pending;
                 watch(dir, { recursive: true }, (_event, filename) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-surfaces/cli",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -22,9 +22,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@agentic-surfaces/core": "0.1.29",
-    "@agentic-surfaces/agent": "0.1.29",
-    "@agentic-surfaces/server": "0.1.29"
+    "@agentic-surfaces/agent": "0.1.30",
+    "@agentic-surfaces/core": "0.1.30",
+    "@agentic-surfaces/server": "0.1.30"
   },
   "repository": {
     "type": "git",