@julioventura/opensquad 0.1.17

package/dashboard/src/plugin/squadWatcher.ts

@@ -0,0 +1,397 @@
+import type { Plugin, ViteDevServer } from "vite";
+import { WebSocketServer, WebSocket } from "ws";
+import type { Server, IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import { watch as chokidarWatch } from "chokidar";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parse as parseYaml } from "yaml";
+import type { SquadInfo, SquadState, WsMessage } from "../types/state";
+
+type WriteDashboardFilesFn = (options: {
+  runDir: string;
+  workspaceRoot: string;
+  outputHtml: string;
+  outputJson: string;
+  templatePath: string;
+  refreshMetrics: boolean;
+}) => Promise<{ payload: unknown }>;
+
+let cachedWriteDashboardFiles: WriteDashboardFilesFn | null = null;
+
+function resolveSquadsDir(): string {
+  const candidates = [
+    path.resolve(process.cwd(), "../squads"),  // started from dashboard/
+    path.resolve(process.cwd(), "squads"),     // started from project root
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return path.resolve(process.cwd(), "../squads"); // default (will be created on demand)
+}
+
+async function discoverSquads(squadsDir: string): Promise<SquadInfo[]> {
+  let entries;
+  try {
+    entries = await fsp.readdir(squadsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const squads: SquadInfo[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".") || entry.name.startsWith("_")) continue;
+
+    const yamlPath = path.join(squadsDir, entry.name, "squad.yaml");
+    try {
+      const raw = await fsp.readFile(yamlPath, "utf-8");
+      const parsed = parseYaml(raw);
+      const s = parsed?.squad;
+      if (s) {
+        squads.push({
+          code: typeof s.code === "string" ? s.code : entry.name,
+          name: typeof s.name === "string" ? s.name : entry.name,
+          description: typeof s.description === "string" ? s.description : "",
+          icon: typeof s.icon === "string" ? s.icon : "\u{1F4CB}",
+          agents: Array.isArray(s.agents) ? (s.agents as unknown[]).filter((a): a is string => typeof a === "string") : [],
+        });
+        continue;
+      }
+    } catch {
+      // No squad.yaml or invalid YAML — fall through to default
+    }
+
+    squads.push({
+      code: entry.name,
+      name: entry.name,
+      description: "",
+      icon: "\u{1F4CB}",
+      agents: [],
+    });
+  }
+
+  return squads;
+}
+
+function isValidState(data: unknown): data is SquadState {
+  if (!data || typeof data !== "object") return false;
+  const d = data as Record<string, unknown>;
+  return (
+    typeof d.status === "string" &&
+    d.step != null && typeof d.step === "object" &&
+    Array.isArray(d.agents)
+  );
+}
+
+async function readActiveStates(squadsDir: string): Promise<Record<string, SquadState>> {
+  const states: Record<string, SquadState> = {};
+
+  let entries;
+  try {
+    entries = await fsp.readdir(squadsDir, { withFileTypes: true });
+  } catch {
+    return states;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const statePath = path.join(squadsDir, entry.name, "state.json");
+
+    try {
+      const raw = await fsp.readFile(statePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (isValidState(parsed)) {
+        states[entry.name] = parsed;
+      }
+    } catch {
+      // Skip missing or invalid JSON
+    }
+  }
+
+  return states;
+}
+
+async function buildSnapshot(squadsDir: string): Promise<WsMessage> {
+  return {
+    type: "SNAPSHOT",
+    squads: await discoverSquads(squadsDir),
+    activeStates: await readActiveStates(squadsDir),
+  };
+}
+
+function broadcast(wss: WebSocketServer, msg: WsMessage) {
+  const data = JSON.stringify(msg);
+  for (const client of wss.clients) {
+    if (client.readyState === WebSocket.OPEN) {
+      try {
+        client.send(data);
+      } catch {
+        // Client connection dying — ws library will clean it up
+      }
+    }
+  }
+}
+
+async function resolveDashboardRunDir(squadsDir: string, squadCode: string): Promise<string | null> {
+  const squadDir = path.join(squadsDir, squadCode);
+  const outputDir = path.join(squadDir, "output");
+
+  if (!fs.existsSync(outputDir)) return null;
+
+  const entries = await fsp.readdir(outputDir, { withFileTypes: true });
+  const candidateDirs = entries
+    .filter((entry) => entry.isDirectory() && entry.name !== "archive" && !entry.name.startsWith("."))
+    .map((entry) => path.join(outputDir, entry.name))
+    .sort((left, right) => path.basename(right).localeCompare(path.basename(left)));
+
+  for (const candidate of candidateDirs) {
+    if (await directoryHasRunDashboardArtifacts(candidate)) return candidate;
+  }
+
+  if (await directoryHasRunDashboardArtifacts(outputDir)) return outputDir;
+  return null;
+}
+
+async function directoryHasRunDashboardArtifacts(targetDir: string): Promise<boolean> {
+  const candidateFiles = [
+    "publish-result.md",
+    "content-package.md",
+    "run-dashboard.html",
+    "run-dashboard.data.json",
+    "state.json",
+  ];
+
+  for (const fileName of candidateFiles) {
+    try {
+      const stats = await fsp.stat(path.join(targetDir, fileName));
+      if (stats.isFile()) return true;
+    } catch {
+      // Keep scanning
+    }
+  }
+
+  return false;
+}
+
+function detectContentType(filePath: string) {
+  const extension = path.extname(filePath).toLowerCase();
+  if (extension === ".html") return "text/html; charset=utf-8";
+  if (extension === ".json") return "application/json; charset=utf-8";
+  if (extension === ".md") return "text/markdown; charset=utf-8";
+  if (extension === ".jpg" || extension === ".jpeg") return "image/jpeg";
+  if (extension === ".png") return "image/png";
+  if (extension === ".webp") return "image/webp";
+  return "application/octet-stream";
+}
+
+function sendJson(res: { setHeader: (name: string, value: string) => void; end: (body: string) => void; writeHead: (code: number) => void }, statusCode: number, payload: unknown) {
+  res.setHeader("Content-Type", "application/json; charset=utf-8");
+  res.setHeader("Cache-Control", "no-store");
+  res.writeHead(statusCode);
+  res.end(JSON.stringify(payload));
+}
+
+async function loadWriteDashboardFiles(workspaceRoot: string): Promise<WriteDashboardFilesFn> {
+  if (cachedWriteDashboardFiles) return cachedWriteDashboardFiles;
+
+  const moduleUrl = pathToFileURL(
+    path.join(workspaceRoot, "skills", "run-dashboard", "scripts", "generate.js"),
+  ).href;
+  const mod = await import(/* @vite-ignore */ moduleUrl) as { writeDashboardFiles: WriteDashboardFilesFn };
+  cachedWriteDashboardFiles = mod.writeDashboardFiles;
+  return cachedWriteDashboardFiles;
+}
+
+export function squadWatcherPlugin(): Plugin {
+  return {
+    name: "squad-watcher",
+    configureServer(server: ViteDevServer) {
+      if (!server.httpServer) {
+        server.config.logger.warn("[squad-watcher] no httpServer — skipping");
+        return;
+      }
+
+      const squadsDir = resolveSquadsDir();
+      server.config.logger.info(`[squad-watcher] squads dir: ${squadsDir}`);
+
+      // Create WebSocket server with noServer to avoid intercepting Vite's HMR
+      const wss = new WebSocketServer({ noServer: true });
+      (server.httpServer as Server).on("upgrade", (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+        if (req.url === "/__squads_ws") {
+          wss.handleUpgrade(req, socket, head, (ws) => {
+            wss.emit("connection", ws, req);
+          });
+        }
+        // Let Vite handle all other upgrade requests (HMR)
+      });
+
+      // Send snapshot on new connection
+      wss.on("connection", async (ws) => {
+        try {
+          const snap = await buildSnapshot(squadsDir);
+          ws.send(JSON.stringify(snap));
+        } catch {
+          // Connection may have closed before snapshot was ready
+        }
+      });
+
+      // Ensure squads directory exists
+      fsp.mkdir(squadsDir, { recursive: true }).catch((err) => {
+        server.config.logger.error(`[squad-watcher] failed to create squads dir: ${err.message}`);
+      });
+
+      // REST API fallback — serves snapshot over HTTP for polling clients
+      server.middlewares.use(async (req, res, next) => {
+        const requestUrl = new URL(req.url || "/", "http://dashboard.local");
+
+        if (requestUrl.pathname === "/api/run-dashboard") {
+          const squadCode = requestUrl.searchParams.get("squad");
+          if (!squadCode) {
+            return sendJson(res, 400, { error: "Missing squad parameter" });
+          }
+
+          const runDir = await resolveDashboardRunDir(squadsDir, squadCode);
+          if (!runDir) {
+            return sendJson(res, 404, { available: false, url: null, runId: null, isLegacyOutputRoot: false });
+          }
+
+          return sendJson(res, 200, {
+            available: true,
+            url: `/__run_dashboard/${encodeURIComponent(squadCode)}/run-dashboard.html`,
+            runId: path.basename(runDir) === "output" ? "legacy-output-root" : path.basename(runDir),
+            isLegacyOutputRoot: path.basename(runDir) === "output",
+          });
+        }
+
+        if (requestUrl.pathname.startsWith("/__run_dashboard/")) {
+          const [, , encodedSquad, ...rest] = requestUrl.pathname.split("/");
+          const squadCode = decodeURIComponent(encodedSquad || "");
+          const runDir = await resolveDashboardRunDir(squadsDir, squadCode);
+          if (!runDir) {
+            res.writeHead(404);
+            res.end("Run dashboard not found");
+            return;
+          }
+
+          const workspaceRoot = path.dirname(squadsDir);
+          const templatePath = path.join(workspaceRoot, "skills", "run-dashboard", "templates", "run-dashboard.template.html");
+          const outputHtml = path.join(runDir, "run-dashboard.html");
+          const outputJson = path.join(runDir, "run-dashboard.data.json");
+          const relativeTarget = rest.join("/") || "run-dashboard.html";
+          const writeDashboardFiles = await loadWriteDashboardFiles(workspaceRoot);
+
+          if (req.method === "POST" && relativeTarget === "__run_dashboard_refresh__") {
+            const { payload } = await writeDashboardFiles({
+              runDir,
+              workspaceRoot,
+              outputHtml,
+              outputJson,
+              templatePath,
+              refreshMetrics: true,
+            });
+            return sendJson(res, 200, payload);
+          }
+
+          if (relativeTarget === "run-dashboard.html" || relativeTarget === "run-dashboard.data.json") {
+            await writeDashboardFiles({
+              runDir,
+              workspaceRoot,
+              outputHtml,
+              outputJson,
+              templatePath,
+              refreshMetrics: false,
+            });
+          }
+
+          const requestedPath = path.resolve(path.join(runDir, relativeTarget));
+          const normalizedRunDir = runDir.toLowerCase();
+          const normalizedRequestedPath = requestedPath.toLowerCase();
+          if (!(normalizedRequestedPath === normalizedRunDir || normalizedRequestedPath.startsWith(`${normalizedRunDir}${path.sep}`))) {
+            res.writeHead(403);
+            res.end("Forbidden");
+            return;
+          }
+
+          try {
+            const content = await fsp.readFile(requestedPath);
+            res.setHeader("Content-Type", detectContentType(requestedPath));
+            res.setHeader("Cache-Control", "no-store");
+            res.end(content);
+          } catch {
+            res.writeHead(404);
+            res.end("Not found");
+          }
+          return;
+        }
+
+        if (requestUrl.pathname !== "/api/snapshot") return next();
+        try {
+          const snapshot = await buildSnapshot(squadsDir);
+          res.setHeader("Content-Type", "application/json");
+          res.setHeader("Cache-Control", "no-cache");
+          res.end(JSON.stringify(snapshot));
+        } catch {
+          res.writeHead(500);
+          res.end("Internal Server Error");
+        }
+      });
+
+      // File watcher using chokidar — reliable cross-platform, handles partial writes
+      const watcher = chokidarWatch(squadsDir, {
+        ignoreInitial: true,
+        awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 50 },
+        ignored: [/(^|[/\\])\./, /node_modules/, /output[/\\]/],
+        depth: 2,
+      });
+
+      function handleFileChange(filePath: string) {
+        const relative = path.relative(squadsDir, filePath).replace(/\\/g, "/");
+        const parts = relative.split("/");
+        if (parts.length < 2) return;
+
+        const squadName = parts[0];
+        const fileName = parts[1];
+
+        if (fileName === "state.json") {
+          fsp.readFile(filePath, "utf-8").then((raw) => {
+            const parsed = JSON.parse(raw);
+            if (!isValidState(parsed)) return;
+            broadcast(wss, { type: "SQUAD_UPDATE", squad: squadName, state: parsed });
+          }).catch(() => {
+            // Invalid JSON — next change event will retry
+          });
+        } else if (fileName === "squad.yaml") {
+          buildSnapshot(squadsDir).then((snap) => broadcast(wss, snap));
+        }
+      }
+
+      function handleFileRemoval(filePath: string) {
+        const relative = path.relative(squadsDir, filePath).replace(/\\/g, "/");
+        const parts = relative.split("/");
+        if (parts.length < 2) return;
+
+        const squadName = parts[0];
+        const fileName = parts[1];
+
+        if (fileName === "state.json") {
+          broadcast(wss, { type: "SQUAD_INACTIVE", squad: squadName });
+        } else if (fileName === "squad.yaml") {
+          buildSnapshot(squadsDir).then((snap) => broadcast(wss, snap));
+        }
+      }
+
+      watcher.on("add", handleFileChange);
+      watcher.on("change", handleFileChange);
+      watcher.on("unlink", handleFileRemoval);
+
+      server.httpServer.on("close", () => {
+        watcher.close();
+      });
+    },
+  };
+}
+

package/dashboard/src/store/useSquadStore.ts

@@ -0,0 +1,56 @@
+import { create } from "zustand";
+import type { SquadInfo, SquadState } from "@/types/state";
+
+interface SquadStore {
+  // State
+  squads: Map<string, SquadInfo>;
+  activeStates: Map<string, SquadState>;
+  selectedSquad: string | null;
+  isConnected: boolean;
+
+  // Actions
+  selectSquad: (name: string | null) => void;
+  setConnected: (connected: boolean) => void;
+  setSnapshot: (squads: SquadInfo[], activeStates: Record<string, SquadState>) => void;
+  setSquadActive: (squad: string, state: SquadState) => void;
+  updateSquadState: (squad: string, state: SquadState) => void;
+  setSquadInactive: (squad: string) => void;
+}
+
+export const useSquadStore = create<SquadStore>((set) => ({
+  squads: new Map(),
+  activeStates: new Map(),
+  selectedSquad: null,
+  isConnected: false,
+
+  selectSquad: (name) => set({ selectedSquad: name }),
+
+  setConnected: (connected) => set({ isConnected: connected }),
+
+  setSnapshot: (squads, activeStates) =>
+    set({
+      squads: new Map(squads.map((s) => [s.code, s])),
+      activeStates: new Map(Object.entries(activeStates)),
+    }),
+
+  setSquadActive: (squad, state) =>
+    set((prev) => ({
+      activeStates: new Map(prev.activeStates).set(squad, state),
+    })),
+
+  updateSquadState: (squad, state) =>
+    set((prev) => ({
+      activeStates: new Map(prev.activeStates).set(squad, state),
+    })),
+
+  setSquadInactive: (squad) =>
+    set((prev) => {
+      const next = new Map(prev.activeStates);
+      next.delete(squad);
+      return {
+        activeStates: next,
+        // Reset selection if the inactive squad was selected
+        selectedSquad: prev.selectedSquad === squad ? null : prev.selectedSquad,
+      };
+    }),
+}));

package/dashboard/src/styles/globals.css

@@ -0,0 +1,36 @@
+*,
+*::before,
+*::after {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+:root {
+  --bg-primary: #101018;
+  --bg-secondary: #1a1a2e;
+  --bg-sidebar: #141422;
+  --border: #2a2a3e;
+  --text-primary: #e0e0e0;
+  --text-secondary: #8888a0;
+  --accent-cyan: #00d4ff;
+  --accent-green: #00e676;
+  --accent-amber: #ffab00;
+  --accent-red: #ff5252;
+}
+
+html,
+body,
+#root {
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+  font-family: "JetBrains Mono", "Fira Code", monospace;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}

package/dashboard/src/types/state.ts

@@ -0,0 +1,63 @@
+// state.json structure — matches Pipeline Runner output
+export interface AgentDesk {
+  col: number;
+  row: number;
+}
+
+export type AgentStatus =
+  | "idle"
+  | "working"
+  | "delivering"
+  | "done"
+  | "checkpoint";
+
+export interface Agent {
+  id: string;
+  name: string;
+  icon: string;
+  status: AgentStatus;
+  gender?: "male" | "female";
+  desk: AgentDesk;
+}
+
+export interface Handoff {
+  from: string;
+  to: string;
+  message: string;
+  completedAt: string;
+}
+
+export type SquadStatus =
+  | "idle"
+  | "running"
+  | "completed"
+  | "checkpoint";
+
+export interface SquadState {
+  squad: string;
+  status: SquadStatus;
+  step: {
+    current: number;
+    total: number;
+    label: string;
+  };
+  agents: Agent[];
+  handoff: Handoff | null;
+  startedAt: string | null;
+  updatedAt: string;
+}
+
+// Squad metadata from squad.yaml
+export interface SquadInfo {
+  code: string;
+  name: string;
+  description: string;
+  icon: string;
+  agents: string[]; // agent file paths
+}
+
+// WebSocket messages
+export type WsMessage =
+  | { type: "SNAPSHOT"; squads: SquadInfo[]; activeStates: Record<string, SquadState> }
+  | { type: "SQUAD_UPDATE"; squad: string; state: SquadState }
+  | { type: "SQUAD_INACTIVE"; squad: string };

package/dashboard/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/dashboard/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}

package/dashboard/vite.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "node:path";
+import { squadWatcherPlugin } from "./src/plugin/squadWatcher";
+
+export default defineConfig({
+  plugins: [react(), squadWatcherPlugin()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@julioventura/opensquad",
+  "version": "0.1.17",
+  "description": "Multi-agent orchestration framework — create AI squads that work together",
+  "type": "module",
+  "bin": {
+    "opensquad": "bin/opensquad.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "lint": "eslint src/ bin/ tests/",
+    "version": "node -e \"require('fs').writeFileSync('templates/_opensquad/.opensquad-version', require('./package.json').version + '\\n')\" && git add templates/_opensquad/.opensquad-version"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "multi-agent",
+    "orchestration",
+    "squads"
+  ],
+  "author": "Renato Asse (https://github.com/renatoasse)",
+  "homepage": "https://github.com/julioventura/opensquad#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julioventura/opensquad.git"
+  },
+  "bugs": {
+    "url": "https://github.com/julioventura/opensquad/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "agents/",
+    "skills/",
+    "templates/",
+    "_opensquad/config/",
+    "_opensquad/core/",
+    "dashboard/",
+    "public/sfx/"
+  ],
+  "dependencies": {
+    "@inquirer/checkbox": "^5.1.0",
+    "@inquirer/input": "^5.0.0",
+    "@inquirer/select": "^5.1.0",
+    "@supabase/supabase-js": "^2.107.0",
+    "basic-ftp": "^5.3.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
+    "playwright": "^1.60.0",
+    "qrcode": "^1.5.4"
+  }
+}