@dadado/agent-kit-cli 4.8.8 → 5.0.0

package/dashboard/lib/broadcast-share.mjs

@@ -0,0 +1,251 @@
+/**
+ * Cosmetic Mission Kit / BYO share URLs for dashboard-broadcast.
+ * Fragment-only payloads (never sent to Hostinger access logs).
+ * ADR: .cursor/memory/decisions/2026-08-11_mission-control-broadcast-url-mask.md
+ */
+
+/** Live Hostinger path uses the `.html` artifact; extensionless `/mc/open` may 404 until a host alias exists. */
+export const DEFAULT_SHARE_BASE = "https://missionkit.io/mc/open.html";
+export const SHARE_BASE_ENV = "MISSION_CONTROL_SHARE_BASE";
+export const SHARE_TTL_ENV = "MISSION_CONTROL_SHARE_TTL_SEC";
+export const SHARE_SHOW_LAN_ENV = "MISSION_CONTROL_SHARE_SHOW_LAN";
+export const DEFAULT_SHARE_TTL_SEC = 86_400;
+
+/**
+ * True when hostname is loopback, link-local, or RFC1918 private (IPv4) / ULA (IPv6).
+ * Used by share-target validation (open redirect harden).
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export function isPrivateOrLoopbackHostname(hostname) {
+  const host = String(hostname || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "");
+  if (!host) return false;
+  if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) return true;
+  if (host === "::1" || host === "0:0:0:0:0:0:0:1") return true;
+  // IPv4 dotted quad
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (m) {
+    const a = Number(m[1]);
+    const b = Number(m[2]);
+    const c = Number(m[3]);
+    const d = Number(m[4]);
+    if ([a, b, c, d].some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return false;
+    if (a === 127) return true; // loopback
+    if (a === 10) return true; // 10/8
+    if (a === 192 && b === 168) return true; // 192.168/16
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16/12
+    if (a === 169 && b === 254) return true; // link-local
+    return false;
+  }
+  // IPv6 ULA fc00::/7 and link-local fe80::/10
+  if (host.includes(":")) {
+    if (host.startsWith("fc") || host.startsWith("fd")) return true;
+    if (
+      host.startsWith("fe8") ||
+      host.startsWith("fe9") ||
+      host.startsWith("fea") ||
+      host.startsWith("feb")
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Validate a decoded share target URL (LAN Mission Control with optional ?token=).
+ * @param {string} url
+ * @returns {{ ok: true, url: string } | { ok: false, error: string }}
+ */
+export function validateBroadcastShareTarget(url) {
+  const raw = typeof url === "string" ? url.trim() : "";
+  if (!raw) return { ok: false, error: "invalid-target" };
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return { ok: false, error: "invalid-target" };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { ok: false, error: "invalid-target" };
+  }
+  if (!isPrivateOrLoopbackHostname(parsed.hostname)) {
+    return { ok: false, error: "non-private-target" };
+  }
+  return { ok: true, url: raw };
+}
+
+/**
+ * Normalize and validate a share page base. Rejects non-HTTPS (except loopback http for local preview).
+ * @param {string} raw
+ * @returns {{ ok: true, base: string } | { ok: false, error: string }}
+ */
+export function normalizeShareBase(raw) {
+  const trimmed = String(raw || "")
+    .trim()
+    .replace(/#.*$/, "")
+    .replace(/\/$/, "");
+  if (!trimmed) return { ok: false, error: "empty-base" };
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { ok: false, error: "invalid-base" };
+  }
+  const host = parsed.hostname.toLowerCase();
+  const loopback =
+    host === "localhost" || host === "127.0.0.1" || host === "::1" || host.endsWith(".localhost");
+  if (parsed.protocol === "https:") {
+    return { ok: true, base: trimmed };
+  }
+  if (parsed.protocol === "http:" && loopback) {
+    return { ok: true, base: trimmed };
+  }
+  return { ok: false, error: "non-https-base" };
+}
+
+/**
+ * GET /open.html and /open are the public cosmetic share-resolver shell under broadcast bind.
+ * All other methods/paths keep the normal token gate.
+ * @param {string} method
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function isPublicBroadcastShareShell(method, pathname) {
+  return method === "GET" && (pathname === "/open.html" || pathname === "/open");
+}
+
+/**
+ * @param {boolean} tokenRequired
+ * @param {string} method
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function shareShellTokenRequired(tokenRequired, method, pathname) {
+  return Boolean(tokenRequired) && !isPublicBroadcastShareShell(method, pathname);
+}
+
+/**
+ * Resolve share page base URL. Empty / "0" / "off" / "false" disables masking.
+ * Non-HTTPS BYO bases (except loopback http) are rejected → masking off (with stderr warn when available).
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {string | null}
+ */
+export function resolveShareBase(env = process.env) {
+  const raw = env?.[SHARE_BASE_ENV];
+  if (raw === undefined || raw === null) return DEFAULT_SHARE_BASE;
+  const trimmed = String(raw).trim();
+  if (!trimmed) return null;
+  const lower = trimmed.toLowerCase();
+  if (lower === "0" || lower === "off" || lower === "false" || lower === "none") return null;
+  const normalized = normalizeShareBase(trimmed);
+  if (!normalized.ok) {
+    if (typeof console !== "undefined" && typeof console.warn === "function") {
+      console.warn(
+        `[broadcast-share] ${SHARE_BASE_ENV} rejected (${normalized.error}); printing LAN URL only. Use HTTPS (or loopback http) or set off.`,
+      );
+    }
+    return null;
+  }
+  return normalized.base;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {number}
+ */
+export function resolveShareTtlSec(env = process.env) {
+  const raw = env?.[SHARE_TTL_ENV];
+  if (raw === undefined || raw === null || String(raw).trim() === "") {
+    return DEFAULT_SHARE_TTL_SEC;
+  }
+  const n = Number.parseInt(String(raw), 10);
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_SHARE_TTL_SEC;
+  return n;
+}
+
+/**
+ * When false, starter omits secondary LAN/Local URL lines (share + token only).
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ */
+export function resolveShareShowLan(env = process.env) {
+  const raw = env?.[SHARE_SHOW_LAN_ENV];
+  if (raw === undefined || raw === null || String(raw).trim() === "") return true;
+  const lower = String(raw).trim().toLowerCase();
+  return !(lower === "0" || lower === "off" || lower === "false" || lower === "no");
+}
+
+/**
+ * @param {string} lanUrl full http URL including ?token=
+ * @param {{ ttlSec?: number, nowSec?: number }} [opts]
+ * @returns {string} fragment without leading '#'
+ */
+export function encodeBroadcastSharePayload(lanUrl, opts = {}) {
+  const url = typeof lanUrl === "string" ? lanUrl.trim() : "";
+  const target = validateBroadcastShareTarget(url);
+  if (!target.ok) {
+    throw new Error(`encodeBroadcastSharePayload: ${target.error}`);
+  }
+  const ttlSec = opts.ttlSec ?? DEFAULT_SHARE_TTL_SEC;
+  /** @type {{ v: number, u: string, e?: number }} */
+  const body = { v: 1, u: target.url };
+  if (ttlSec > 0) {
+    const now = opts.nowSec ?? Math.floor(Date.now() / 1000);
+    body.e = now + ttlSec;
+  }
+  return `v1.${Buffer.from(JSON.stringify(body), "utf8").toString("base64url")}`;
+}
+
+/**
+ * @param {string} lanUrl
+ * @param {{ base?: string | null, ttlSec?: number, nowSec?: number }} [opts]
+ * @returns {string | null}
+ */
+export function buildBroadcastShareUrl(lanUrl, opts = {}) {
+  const base = opts.base === undefined ? DEFAULT_SHARE_BASE : opts.base;
+  if (!base) return null;
+  const cleaned = String(base).replace(/#.*$/, "").replace(/\/$/, "");
+  const frag = encodeBroadcastSharePayload(lanUrl, opts);
+  return `${cleaned}#${frag}`;
+}
+
+/**
+ * @param {string} fragment hash with or without leading '#'
+ * @param {{ nowSec?: number }} [opts]
+ * @returns
+ *   | { ok: true, url: string, expiresAt: number | null }
+ *   | { ok: false, error: string }
+ */
+export function decodeBroadcastShareFragment(fragment, opts = {}) {
+  const raw = String(fragment || "")
+    .replace(/^#/, "")
+    .trim();
+  if (!raw) return { ok: false, error: "missing-fragment" };
+  const m = /^v1\.([A-Za-z0-9_-]+)$/.exec(raw);
+  if (!m) return { ok: false, error: "unsupported-version" };
+  let parsed;
+  try {
+    const json = Buffer.from(m[1], "base64url").toString("utf8");
+    parsed = JSON.parse(json);
+  } catch {
+    return { ok: false, error: "invalid-payload" };
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.v !== 1) {
+    return { ok: false, error: "unsupported-version" };
+  }
+  const url = typeof parsed.u === "string" ? parsed.u.trim() : "";
+  const target = validateBroadcastShareTarget(url);
+  if (!target.ok) return { ok: false, error: target.error };
+  let expiresAt = null;
+  if (parsed.e !== undefined && parsed.e !== null) {
+    const e = Number(parsed.e);
+    if (!Number.isFinite(e)) return { ok: false, error: "invalid-expiry" };
+    expiresAt = e;
+    const now = opts.nowSec ?? Math.floor(Date.now() / 1000);
+    if (now > e) return { ok: false, error: "expired" };
+  }
+  return { ok: true, url: target.url, expiresAt };
+}

package/dashboard/lib/guards.d.mts

@@ -0,0 +1,10 @@
+/** Ambient types for dashboard/lib/guards.mjs (consumed by CLI TypeScript). */
+
+export function resolveContextConfigPath(
+  repoRoot: string,
+  fsHooks?: {
+    existsSync?: (path: string) => boolean;
+    realpathSync?: (path: string) => string;
+    mkdirSync?: (path: string, opts?: { recursive?: boolean }) => void;
+  },
+): { ok: true; path: string } | { ok: false; error: string };

package/dashboard/lib/guards.mjs

@@ -675,12 +675,17 @@ export function validateConfigWriteBody(body) {
       if (!modes || typeof modes !== "object" || Array.isArray(modes)) {
         return { ok: false, error: "agentPersona.modes must be an object" };
       }
-      /** @type {Record<string, string>} */
+      /** @type {Record<string, string | null>} */
       const modesPatch = {};
       for (const [mode, persona] of Object.entries(modes)) {
         if (!CONFIG_PERSONA_MODES.includes(mode)) {
           return { ok: false, error: `unknown agentPersona.modes key: ${mode}` };
         }
+        // null clears an existing mode override (Inherit default).
+        if (persona === null) {
+          modesPatch[mode] = null;
+          continue;
+        }
         if (typeof persona !== "string" || !CONFIG_PERSONA_IDS.includes(persona)) {
           return { ok: false, error: `agentPersona.modes.${mode} must be a builtin persona id` };
         }
@@ -767,7 +772,15 @@ export function mergeConfigAllowlist(existing, patch) {
         prev.modes && typeof prev.modes === "object" && !Array.isArray(prev.modes)
           ? { ...prev.modes }
           : {};
-      next.modes = { ...prevModes, ...patch.agentPersona.modes };
+      const nextModes = { ...prevModes };
+      for (const [mode, persona] of Object.entries(patch.agentPersona.modes)) {
+        if (persona === null) {
+          delete nextModes[mode];
+        } else {
+          nextModes[mode] = persona;
+        }
+      }
+      next.modes = nextModes;
     }
     base.agentPersona = next;
   }

package/dashboard/lib/open-browser.d.mts

@@ -0,0 +1,31 @@
+import type { spawn, spawnSync } from "node:child_process";
+import type { readFileSync } from "node:fs";
+
+export const OS_DEFAULT_TOKENS: Set<string>;
+export function isSafePreferredBrowser(value: string): boolean;
+export function shouldSkipOpen(env?: NodeJS.ProcessEnv): boolean;
+export function normalizePreferredBrowser(value: unknown): string | null;
+export function resolvePreferredBrowser(opts?: {
+  env?: NodeJS.ProcessEnv;
+  configValue?: unknown;
+}): string | null;
+export function readPreferredBrowserFromConfig(
+  configPath: string,
+  fsHooks?: { readFileSync?: typeof readFileSync },
+): unknown;
+export function buildOpenBrowserCommand(opts: {
+  url: string;
+  preferred?: string | null;
+  platform?: NodeJS.Platform;
+}): { command: string; args: string[] } | null;
+export function openBrowser(
+  url: string,
+  options?: {
+    env?: NodeJS.ProcessEnv;
+    preferred?: string | null;
+    configValue?: unknown;
+    platform?: NodeJS.Platform;
+    spawnFn?: typeof spawn;
+    spawnSyncFn?: typeof spawnSync;
+  },
+): { opened: boolean; reason?: string; command?: string; args?: string[] };

package/dashboard/lib/open-browser.mjs

@@ -0,0 +1,298 @@
+/**
+ * Shared Mission Control browser open helper.
+ *
+ * Preference resolution (highest wins):
+ *   1. env MISSION_CONTROL_PREFERRED_BROWSER
+ *   2. config missionControl.preferredBrowser (passed in by caller)
+ *   3. OS default handler (null preferred)
+ *
+ * Skips open when MISSION_CONTROL_NO_OPEN=1.
+ * Never opens more than one process per call (preferred may fall back once).
+ *
+ * Trust boundary: preferredBrowser is an app/binary *name*, not a path or
+ * shell expression. Values with path separators or shell metacharacters are
+ * rejected and treated as OS default.
+ *
+ * ADR: .cursor/memory/decisions/2026-08-11_mission-control-preferred-browser.md
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { platform as osPlatform } from "node:os";
+
+/** Sentinel values that mean "use OS default" (and slash-only Ask). */
+export const OS_DEFAULT_TOKENS = new Set(["", "default", "os", "ask"]);
+
+/**
+ * Reject path separators, absolute/relative path forms, and shell metacharacters.
+ * Allowed examples: "Google Chrome", "firefox", "msedge", "Brave Browser".
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isSafePreferredBrowser(value) {
+  if (typeof value !== "string") return false;
+  const s = value.trim();
+  if (!s) return false;
+  if (/[/\\]/.test(s)) return false;
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional reject of C0/DEL in browser names
+  if (/[\0-\x1f\x7f]/.test(s)) return false;
+  if (/[$`;&|<>(){}[\]!*?#~"'%^=,+]/.test(s)) return false;
+  if (s.includes(":")) return false;
+  if (/^-/.test(s)) return false;
+  return true;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function shouldSkipOpen(env = process.env) {
+  return env.MISSION_CONTROL_NO_OPEN === "1";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | null} trimmed app/binary name, or null for OS default
+ */
+export function normalizePreferredBrowser(value) {
+  if (value == null) return null;
+  const s = String(value).trim();
+  if (!s || OS_DEFAULT_TOKENS.has(s.toLowerCase())) return null;
+  if (!isSafePreferredBrowser(s)) return null;
+  return s;
+}
+
+/**
+ * @param {{ env?: NodeJS.ProcessEnv, configValue?: unknown }} [opts]
+ * @returns {string | null}
+ */
+export function resolvePreferredBrowser(opts = {}) {
+  const env = opts.env ?? process.env;
+  const fromEnv = env.MISSION_CONTROL_PREFERRED_BROWSER;
+  if (fromEnv != null && String(fromEnv).trim() !== "") {
+    return normalizePreferredBrowser(fromEnv);
+  }
+  return normalizePreferredBrowser(opts.configValue);
+}
+
+/**
+ * Read missionControl.preferredBrowser from a context config.json path.
+ * Missing/invalid file → null (OS default). Does not create the file.
+ *
+ * @param {string} configPath
+ * @param {{ readFileSync?: typeof readFileSync }} [fsHooks]
+ * @returns {unknown}
+ */
+export function readPreferredBrowserFromConfig(configPath, fsHooks = {}) {
+  const read = fsHooks.readFileSync ?? readFileSync;
+  try {
+    const raw = read(configPath, "utf8");
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+    const mc = data.missionControl;
+    if (!mc || typeof mc !== "object" || Array.isArray(mc)) return null;
+    return mc.preferredBrowser ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build an argv for a single open attempt (hermetic: no spawn).
+ *
+ * @param {{
+ *   url: string,
+ *   preferred?: string | null,
+ *   platform?: NodeJS.Platform,
+ * }} opts
+ * @returns {{ command: string, args: string[] } | null}
+ */
+export function buildOpenBrowserCommand(opts) {
+  const url = opts.url;
+  if (typeof url !== "string" || !url.trim()) return null;
+  const preferred = normalizePreferredBrowser(opts.preferred ?? null);
+  const os = opts.platform ?? osPlatform();
+
+  if (os === "darwin") {
+    if (preferred) {
+      return { command: "open", args: ["-a", preferred, url] };
+    }
+    return { command: "open", args: [url] };
+  }
+
+  if (os === "win32") {
+    if (preferred) {
+      // `start` treats the first quoted arg as window title; pass empty title.
+      return { command: "cmd", args: ["/c", "start", "", preferred, url] };
+    }
+    return { command: "cmd", args: ["/c", "start", "", url] };
+  }
+
+  // Linux / other: preferred is a binary or command name; else xdg-open.
+  if (preferred) {
+    return { command: preferred, args: [url] };
+  }
+  return { command: "xdg-open", args: [url] };
+}
+
+/**
+ * @param {import("node:child_process").ChildProcess | { on?: Function, unref?: Function } | null | undefined} child
+ */
+function attachErrorSwallow(child) {
+  if (child && typeof child.on === "function") {
+    child.on("error", () => {
+      /* prevent unhandled 'error' (ENOENT) from killing the launcher */
+    });
+  }
+  if (child && typeof child.unref === "function") {
+    child.unref();
+  }
+}
+
+/**
+ * Open one browser for the URL. Returns whether a process was spawned.
+ * When a preferred open fails, falls back once to the OS default opener.
+ *
+ * @param {string} url
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   preferred?: string | null,
+ *   configValue?: unknown,
+ *   platform?: NodeJS.Platform,
+ *   spawnFn?: typeof spawn,
+ *   spawnSyncFn?: typeof spawnSync,
+ * }} [options]
+ * @returns {{ opened: boolean, reason?: string, command?: string, args?: string[] }}
+ */
+export function openBrowser(url, options = {}) {
+  const env = options.env ?? process.env;
+  if (shouldSkipOpen(env)) {
+    return { opened: false, reason: "no-open" };
+  }
+
+  const preferred =
+    options.preferred !== undefined
+      ? normalizePreferredBrowser(options.preferred)
+      : resolvePreferredBrowser({ env, configValue: options.configValue });
+
+  const platform = options.platform ?? osPlatform();
+  const spawnFn = options.spawnFn ?? spawn;
+  const spawnSyncFn = options.spawnSyncFn;
+
+  /**
+   * @param {{ command: string, args: string[] }} built
+   * @returns {{ opened: boolean, reason?: string, command: string, args: string[] }}
+   */
+  function runDetached(built) {
+    try {
+      const child = spawnFn(built.command, built.args, { detached: true, stdio: "ignore" });
+      attachErrorSwallow(child);
+      return { opened: true, command: built.command, args: built.args };
+    } catch {
+      return {
+        opened: false,
+        reason: "spawn-failed",
+        command: built.command,
+        args: built.args,
+      };
+    }
+  }
+
+  /**
+   * Preferred open: detect failure before claiming success, then caller may fall back.
+   * Hermetic tests that only inject spawnFn use the detached path (throw = fail).
+   *
+   * @param {{ command: string, args: string[] }} built
+   * @returns {{ opened: boolean, reason?: string, command: string, args: string[] }}
+   */
+  function runPreferred(built) {
+    if (options.spawnFn && !spawnSyncFn) {
+      return runDetached(built);
+    }
+
+    const sync = spawnSyncFn ?? spawnSync;
+
+    if (platform !== "darwin" && platform !== "win32") {
+      // Long-lived browser binaries: probe PATH, then detach (do not spawnSync the app).
+      const probe = sync("which", [built.command], { encoding: "utf8" });
+      if (probe.error || (typeof probe.status === "number" && probe.status !== 0)) {
+        return {
+          opened: false,
+          reason: "spawn-failed",
+          command: built.command,
+          args: built.args,
+        };
+      }
+      return runDetached(built);
+    }
+
+    // darwin `open` / win32 `cmd /c start` exit quickly.
+    try {
+      const result = sync(built.command, built.args, {
+        encoding: "utf8",
+        windowsHide: true,
+      });
+      if (result.error || (typeof result.status === "number" && result.status !== 0)) {
+        return {
+          opened: false,
+          reason: "spawn-failed",
+          command: built.command,
+          args: built.args,
+        };
+      }
+      return { opened: true, command: built.command, args: built.args };
+    } catch {
+      return {
+        opened: false,
+        reason: "spawn-failed",
+        command: built.command,
+        args: built.args,
+      };
+    }
+  }
+
+  const built = buildOpenBrowserCommand({
+    url,
+    preferred,
+    platform,
+  });
+  if (!built) {
+    return { opened: false, reason: "invalid-url" };
+  }
+
+  if (!preferred) {
+    // Same failure detection as preferred opens (probe / spawnSync) so OS-default
+    // missing handlers are not reported as opened:true.
+    return runPreferred(built);
+  }
+
+  const prefResult = runPreferred(built);
+  if (prefResult.opened) {
+    return prefResult;
+  }
+
+  const fallback = buildOpenBrowserCommand({
+    url,
+    preferred: null,
+    platform,
+  });
+  if (!fallback) {
+    return { opened: false, reason: "invalid-url" };
+  }
+  const fb = runPreferred(fallback);
+  if (fb.opened) {
+    return {
+      opened: true,
+      command: fb.command,
+      args: fb.args,
+      reason: "preferred-fallback",
+    };
+  }
+  return {
+    opened: false,
+    reason: "spawn-failed",
+    command: built.command,
+    args: built.args,
+  };
+}