@hacksmith/doraval 0.2.44 → 0.2.46

package/README.md

@@ -1,10 +1,14 @@
 # doraval
 
-The context engineering toolkit for coding agents.
+The context engineering toolkit for coding agent orchestrators.
 
-If you've ever shipped a Claude Code skill that stopped firing after a refactor, or wondered whether your plugin's structure actually matches what the agent expects — doraval validates that before it becomes a runtime surprise.
+If you're a senior engineer handing skills to new team members, a company publishing AI resources, or anyone who wants agents (and humans) to succeed on the first attempt instead of after days of debugging — this is for you.
 
-> **Quick start:**
+**The orchestrator problem:** Give 10 new engineers (or agents) a skill and only 3/10 succeed on the first try. 4/10 take hours. 7/10 take a day. 10/10 take days.
+
+doraval helps you **left-shift success** — validate, scaffold, and manage context so the first attempt works across Claude, Cursor, Codex, Copilot, and whatever comes next.
+
+> **Quick start (left-shift success in < 2 minutes):**
 > ```bash
 > # macOS
 > brew install saif-shines/tap/doraval
@@ -14,7 +18,7 @@ If you've ever shipped a Claude Code skill that stopped firing after a refactor,
 > npx @hacksmith/doraval validate .
 > ```
 
-Point it at any local directory or GitHub URL. It auto-detects what you have and tells you what's broken.
+Validate before you hand a skill to a new engineer or publish it. It auto-detects issues across agents and tells you what's broken.
 
 ## Install
 
@@ -144,6 +148,17 @@ doraval journal update        # pull latest from remote
 
 Requires the GitHub CLI (`gh`). Journal lives in a private GitHub repo you control.
 
+### `ui` — Local dashboard (avoid typing repetitive commands)
+
+```bash
+doraval ui                 # start the web dashboard (opens browser)
+doraval ui --port 4921     # different port
+doraval ui --status        # check if running + show URL
+doraval ui --force         # force restart
+```
+
+Re-running `doraval ui` is now idempotent (uses PID tracking). Use `--force` to restart.
+
 doraval update              # self-update doraval to the latest version
 doraval claude new          # interactive wizard for skills/plugins (follows official table)
 

package/bin/doraval.js

@@ -599,7 +599,7 @@ var init_dist = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hacksmith/doraval",
-    version: "0.2.44",
+    version: "0.2.46",
     author: "Saif",
     repository: {
       type: "git",
@@ -612,7 +612,7 @@ var require_package = __commonJS((exports, module) => {
       doraval: "bin/doraval-wrapper.js",
       dora: "bin/doraval-wrapper.js"
     },
-    description: "The context engineering toolkit for coding agents",
+    description: "The context engineering toolkit for coding agent orchestrators",
     engines: {
       bun: ">=1.2.0",
       node: ">=14.18.0"
@@ -4367,7 +4367,7 @@ var exports_ui = {};
 __export(exports_ui, {
   default: () => ui_default
 });
-import { existsSync as existsSync19, readdirSync as readdirSync9 } from "fs";
+import { existsSync as existsSync19, readdirSync as readdirSync9, writeFileSync as writeFileSync6, unlinkSync as unlinkSync2, readFileSync as readFileSync2 } from "fs";
 import { join as join18 } from "path";
 import { spawn } from "child_process";
 function slugify2(title) {
@@ -4457,6 +4457,34 @@ async function killPort(port) {
     await new Promise((r) => setTimeout(r, 400));
   } catch {}
 }
+function readPid(p) {
+  const file = getPidFile(p);
+  if (!existsSync19(file))
+    return null;
+  try {
+    const raw = readFileSync2(file, "utf8").trim();
+    const pid = parseInt(raw, 10);
+    if (isNaN(pid))
+      return null;
+    process.kill(pid, 0);
+    return pid;
+  } catch {
+    try {
+      unlinkSync2(file);
+    } catch {}
+    return null;
+  }
+}
+function writePid(pid, p) {
+  ensureDoravalDirs();
+  writeFileSync6(getPidFile(p), String(pid) + `
+`);
+}
+function removePid(p) {
+  try {
+    unlinkSync2(getPidFile(p));
+  } catch {}
+}
 async function getDashboardHtml() {
   const isSource = import.meta.url.includes("/src/");
   const htmlPath = isSource ? new URL("../../ui/index.html", import.meta.url) : new URL("./ui/index.html", import.meta.url);
@@ -4467,7 +4495,7 @@ async function getDashboardHtml() {
     return `<!doctype html><meta charset="utf-8"><body style="font-family:monospace;background:#111;color:#ddd;padding:2rem"><h1>doraval ui</h1><p>Dashboard HTML missing.</p><pre>${String(err)}</pre></body>`;
   }
 }
-var import_picocolors16, DEFAULT_PORT = 3737, ui_default;
+var import_picocolors16, DEFAULT_PORT = 3737, getPidFile = (p) => join18(getDoravalDir(), `ui.${p}.pid`), ui_default;
 var init_ui = __esm(() => {
   init_journal_config();
   init_journal_parse();
@@ -4479,7 +4507,42 @@ var init_ui = __esm(() => {
       const port = Number(args.port) || DEFAULT_PORT;
       const host = args.host || "127.0.0.1";
       const shouldOpen = args.open !== false;
-      await killPort(port);
+      const showStatusOnly = !!args.status;
+      const force = !!args.force;
+      ensureDoravalDirs();
+      const existingPid = readPid(port);
+      if (showStatusOnly) {
+        if (existingPid) {
+          const url2 = `http://${host === "0.0.0.0" ? "localhost" : host}:${port}`;
+          console.error(`  Dashboard running (pid ${existingPid})`);
+          console.error(`  URL:     ${import_picocolors16.default.underline(import_picocolors16.default.cyan(url2))}`);
+        } else {
+          console.error(`  No dashboard running.`);
+        }
+        return;
+      }
+      if (existingPid && !force) {
+        const url2 = `http://${host === "0.0.0.0" ? "localhost" : host}:${port}`;
+        console.error(`  Dashboard already running (pid ${existingPid}).`);
+        console.error(`  URL:     ${import_picocolors16.default.underline(import_picocolors16.default.cyan(url2))}`);
+        if (shouldOpen && process.stdout.isTTY) {
+          try {
+            const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+            spawn(opener, [url2], { stdio: "ignore", detached: true }).unref();
+          } catch {}
+        }
+        return;
+      }
+      if (existingPid && force) {
+        console.error(`  Force restarting (killing pid ${existingPid})...`);
+        try {
+          process.kill(existingPid, "SIGTERM");
+        } catch {}
+        await new Promise((r) => setTimeout(r, 400));
+        removePid(port);
+      } else if (!existingPid) {
+        await killPort(port);
+      }
       const config = await readConfig();
       let project = resolveProjectName(config) ?? undefined;
       if (project) {
@@ -4489,105 +4552,113 @@ var init_ui = __esm(() => {
           project = undefined;
         }
       }
-      const server = Bun.serve({
-        port,
-        hostname: host,
-        async fetch(req) {
-          const url2 = new URL(req.url);
-          if (url2.pathname === "/" || url2.pathname === "/index.html") {
-            const html = await getDashboardHtml();
-            return new Response(html, {
-              headers: { "content-type": "text/html; charset=utf-8" }
-            });
-          }
-          if (url2.pathname === "/api/status") {
-            return Response.json({
-              project: project || null,
-              doravalDir: getJournalsDir(),
-              hasConfig: !!config,
-              repo: config?.journal?.repo ?? null
-            });
-          }
-          if (url2.pathname === "/api/entries") {
-            const { committed, staged } = await loadAllEntries(project || null);
-            return Response.json({ project, committed, staged });
-          }
-          if (url2.pathname === "/api/context") {
-            const { committed, staged } = await loadAllEntries(project || null);
-            const all = [...staged, ...committed].filter((e) => (e.status || "active") === "active");
-            const text = generateJournalContext(all, project || null, { minPushback: 1 });
-            return Response.json({ text, project });
-          }
-          if (url2.pathname === "/api/hooks/status" && req.method === "GET") {
-            const localPath = getLocalHooksPath();
-            const globalPath = getGlobalSettingsPath();
-            const localHas = hasHook(await readJson(localPath));
-            const globalHas = hasHook(await readJson(globalPath));
-            return Response.json({
-              local: { enabled: localHas, path: localPath },
-              global: { enabled: globalHas, path: globalPath }
-            });
-          }
-          if (url2.pathname === "/api/hooks/enable" && req.method === "POST") {
-            const body = await req.json().catch(() => ({}));
-            const useGlobal = !!body.global;
-            const target = useGlobal ? getGlobalSettingsPath() : getLocalHooksPath();
-            const res = await addHook(target);
-            return Response.json(res);
-          }
-          if (url2.pathname === "/api/hooks/disable" && req.method === "POST") {
-            const body = await req.json().catch(() => ({}));
-            const useGlobal = !!body.global;
-            const target = useGlobal ? getGlobalSettingsPath() : getLocalHooksPath();
-            const res = await removeHook(target);
-            return Response.json(res);
-          }
-          if (url2.pathname === "/api/add" && req.method === "POST") {
-            if (!project) {
-              return Response.json({ error: "No project configured. Run dora init or dora journal init first." }, { status: 400 });
+      let server;
+      try {
+        server = Bun.serve({
+          port,
+          hostname: host,
+          async fetch(req) {
+            const url2 = new URL(req.url);
+            if (url2.pathname === "/" || url2.pathname === "/index.html") {
+              const html = await getDashboardHtml();
+              return new Response(html, {
+                headers: { "content-type": "text/html; charset=utf-8" }
+              });
             }
-            const body = await req.json();
-            const title = String(body.title || "Untitled decision").trim();
-            const pushback = Number(body.pushback ?? 4);
-            const tags = Array.isArray(body.tags) ? body.tags.map((t) => String(t).trim()).filter(Boolean) : [];
-            const rationale = String(body.rationale || title).trim();
-            try {
-              const result = await writePendingEntry(project, { title, pushback, tags, rationale });
-              return Response.json({ ok: true, ...result });
-            } catch (e) {
-              return Response.json({ error: e.message }, { status: 500 });
+            if (url2.pathname === "/api/status") {
+              return Response.json({
+                project: project || null,
+                doravalDir: getJournalsDir(),
+                hasConfig: !!config,
+                repo: config?.journal?.repo ?? null
+              });
             }
-          }
-          if (url2.pathname === "/api/refresh" && req.method === "POST") {
-            const { committed, staged } = await loadAllEntries(project || null);
-            return Response.json({ ok: true, committed, staged });
-          }
-          if (url2.pathname === "/api/delete-staged" && req.method === "POST") {
-            if (!project) {
-              return Response.json({ error: "No project" }, { status: 400 });
+            if (url2.pathname === "/api/entries") {
+              const { committed, staged } = await loadAllEntries(project || null);
+              return Response.json({ project, committed, staged });
+            }
+            if (url2.pathname === "/api/context") {
+              const { committed, staged } = await loadAllEntries(project || null);
+              const all = [...staged, ...committed].filter((e) => (e.status || "active") === "active");
+              const text = generateJournalContext(all, project || null, { minPushback: 1 });
+              return Response.json({ text, project });
             }
-            const body = await req.json().catch(() => ({}));
-            const filename = body.filename;
-            if (!filename) {
-              return Response.json({ error: "filename required" }, { status: 400 });
+            if (url2.pathname === "/api/hooks/status" && req.method === "GET") {
+              const localPath = getLocalHooksPath();
+              const globalPath = getGlobalSettingsPath();
+              const localHas = hasHook(await readJson(localPath));
+              const globalHas = hasHook(await readJson(globalPath));
+              return Response.json({
+                local: { enabled: localHas, path: localPath },
+                global: { enabled: globalHas, path: globalPath }
+              });
             }
-            const pdir = getPendingProjectDir(project);
-            const filePath = join18(pdir, filename);
-            if (existsSync19(filePath)) {
+            if (url2.pathname === "/api/hooks/enable" && req.method === "POST") {
+              const body = await req.json().catch(() => ({}));
+              const useGlobal = !!body.global;
+              const target = useGlobal ? getGlobalSettingsPath() : getLocalHooksPath();
+              const res = await addHook(target);
+              return Response.json(res);
+            }
+            if (url2.pathname === "/api/hooks/disable" && req.method === "POST") {
+              const body = await req.json().catch(() => ({}));
+              const useGlobal = !!body.global;
+              const target = useGlobal ? getGlobalSettingsPath() : getLocalHooksPath();
+              const res = await removeHook(target);
+              return Response.json(res);
+            }
+            if (url2.pathname === "/api/add" && req.method === "POST") {
+              if (!project) {
+                return Response.json({ error: "No project configured. Run dora init or dora journal init first." }, { status: 400 });
+              }
+              const body = await req.json();
+              const title = String(body.title || "Untitled decision").trim();
+              const pushback = Number(body.pushback ?? 4);
+              const tags = Array.isArray(body.tags) ? body.tags.map((t) => String(t).trim()).filter(Boolean) : [];
+              const rationale = String(body.rationale || title).trim();
               try {
-                await Bun.file(filePath).unlink();
-              } catch {}
-              return Response.json({ ok: true });
+                const result = await writePendingEntry(project, { title, pushback, tags, rationale });
+                return Response.json({ ok: true, ...result });
+              } catch (e) {
+                return Response.json({ error: e.message }, { status: 500 });
+              }
             }
-            return Response.json({ error: "not found" }, { status: 404 });
-          }
-          if (url2.pathname.startsWith("/api/")) {
-            return Response.json({ error: "Not found" }, { status: 404 });
+            if (url2.pathname === "/api/refresh" && req.method === "POST") {
+              const { committed, staged } = await loadAllEntries(project || null);
+              return Response.json({ ok: true, committed, staged });
+            }
+            if (url2.pathname === "/api/delete-staged" && req.method === "POST") {
+              if (!project) {
+                return Response.json({ error: "No project" }, { status: 400 });
+              }
+              const body = await req.json().catch(() => ({}));
+              const filename = body.filename;
+              if (!filename) {
+                return Response.json({ error: "filename required" }, { status: 400 });
+              }
+              const pdir = getPendingProjectDir(project);
+              const filePath = join18(pdir, filename);
+              if (existsSync19(filePath)) {
+                try {
+                  await Bun.file(filePath).unlink();
+                } catch {}
+                return Response.json({ ok: true });
+              }
+              return Response.json({ error: "not found" }, { status: 404 });
+            }
+            if (url2.pathname.startsWith("/api/")) {
+              return Response.json({ error: "Not found" }, { status: 404 });
+            }
+            return new Response("Not found", { status: 404 });
           }
-          return new Response("Not found", { status: 404 });
-        }
-      });
+        });
+      } catch (err) {
+        removePid(port);
+        console.error(`  Failed to start dashboard on port ${port}: ${err?.message || err}`);
+        process.exit(1);
+      }
       const url = `http://${host === "0.0.0.0" ? "localhost" : host}:${server.port}`;
+      writePid(process.pid, port);
       const msg = `
   ${import_picocolors16.default.blue("\u25C9")}  dora local dashboard
   ${import_picocolors16.default.dim("Project:")} ${project ? import_picocolors16.default.white(project) : import_picocolors16.default.yellow("none (run dora init)")}
@@ -4604,12 +4675,15 @@ var init_ui = __esm(() => {
           console.error(import_picocolors16.default.dim(`  Could not auto-open. Visit ${url}`));
         }
       }
-      process.on("SIGINT", () => {
+      const cleanup = () => {
+        removePid(port);
         console.error(`
   Stopping dashboard...`);
         server.stop();
         process.exit(0);
-      });
+      };
+      process.on("SIGINT", cleanup);
+      process.on("SIGTERM", cleanup);
     }
   };
 });
@@ -7733,7 +7807,7 @@ var exports_completion = {};
 __export(exports_completion, {
   default: () => completion_default
 });
-var commands, subCommands, completion_default;
+var commands, uiFlags, subCommands, completion_default;
 var init_completion = __esm(() => {
   init_dist();
   commands = [
@@ -7750,6 +7824,7 @@ var init_completion = __esm(() => {
     "cursor",
     "copilot"
   ];
+  uiFlags = ["--port", "--open", "--no-open", "--host", "--status", "--force"];
   subCommands = {
     skill: ["validate", "drift", "judge"],
     journal: ["init", "list", "context", "hook", "update", "add", "sync"],
@@ -7788,6 +7863,7 @@ _doraval_completions() {
       skill) COMPREPLY=( $(compgen -W "${subCommands.skill.join(" ")}" -- "$cur") ) ;;
       journal) COMPREPLY=( $(compgen -W "${subCommands.journal.join(" ")}" -- "$cur") ) ;;
       hook) COMPREPLY=( $(compgen -W "${subCommands.hook.join(" ")}" -- "$cur") ) ;;
+      ui) COMPREPLY=( $(compgen -W "${uiFlags.join(" ")}" -- "$cur") ) ;;
       claude|codex|cursor|copilot) COMPREPLY=( $(compgen -W "${subCommands.claude.join(" ")}" -- "$cur") ) ;;
     esac
   fi
@@ -7820,6 +7896,9 @@ _doraval() {
         hook)
           _describe 'subcommand' (enable disable status)
           ;;
+        ui)
+          _describe 'flag' (${uiFlags})
+          ;;
         claude|codex|cursor|copilot)
           _describe 'subcommand' (new bump)
           ;;
@@ -7838,6 +7917,12 @@ complete -c doraval -n '__fish_use_subcommand' -a 'validate init bump update pro
 complete -c doraval -n '__fish_seen_subcommand_from skill' -a 'validate drift judge'
 complete -c doraval -n '__fish_seen_subcommand_from journal' -a 'init list context hook update add sync'
 complete -c doraval -n '__fish_seen_subcommand_from hook' -a 'enable disable status'
+complete -c doraval -n '__fish_seen_subcommand_from ui' -l port -d 'Port'
+complete -c doraval -n '__fish_seen_subcommand_from ui' -l open -d 'Open browser'
+complete -c doraval -n '__fish_seen_subcommand_from ui' -l no-open -d 'Do not open browser'
+complete -c doraval -n '__fish_seen_subcommand_from ui' -l host -d 'Host'
+complete -c doraval -n '__fish_seen_subcommand_from ui' -l status -d 'Show status only'
+complete -c doraval -n '__fish_seen_subcommand_from ui' -l force -d 'Force restart'
 complete -c doraval -n '__fish_seen_subcommand_from claude codex cursor copilot' -a 'new bump'
 `);
       } else {
@@ -7975,6 +8060,16 @@ var ui2 = defineCommand({
       type: "string",
       description: "Host to bind (default 127.0.0.1 for local only)",
       default: "127.0.0.1"
+    },
+    status: {
+      type: "boolean",
+      description: "Check if a dashboard is running and print its URL (no start)",
+      default: false
+    },
+    force: {
+      type: "boolean",
+      description: "Force start/restart even if one is already running",
+      default: false
     }
   },
   async run({ args }) {
@@ -7997,7 +8092,7 @@ var main = defineCommand({
   meta: {
     name: "doraval",
     version: import__package.default.version,
-    description: "The context engineering toolkit for coding agents"
+    description: "The context engineering toolkit for coding agent orchestrators"
   },
   subCommands: {
     validate: () => Promise.resolve().then(() => (init_validate_top(), exports_validate_top)).then((m) => m.default),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hacksmith/doraval",
-  "version": "0.2.44",
+  "version": "0.2.46",
   "author": "Saif",
   "repository": {
     "type": "git",
@@ -13,7 +13,7 @@
     "doraval": "bin/doraval-wrapper.js",
     "dora": "bin/doraval-wrapper.js"
   },
-  "description": "The context engineering toolkit for coding agents",
+  "description": "The context engineering toolkit for coding agent orchestrators",
   "engines": {
     "bun": ">=1.2.0",
     "node": ">=14.18.0"