@blackbelt-technology/pi-agent-dashboard 0.4.0 → 0.4.2

package/packages/shared/src/config.ts

@@ -80,6 +80,12 @@ export interface KnownServer {
   addedAt: string; // ISO timestamp
 }
 
+/**
+ * Plugin-specific config namespace.
+ * Lives at ~/.pi/dashboard/config.json#plugins.<id>.*
+ */
+export type PluginsConfig = Record<string, Record<string, unknown>>;
+
 export interface DashboardConfig {
   port: number;
   piPort: number;
@@ -107,6 +113,13 @@ export interface DashboardConfig {
   electronMode: boolean;
   /** Persisted list of known remote servers */
   knownServers: KnownServer[];
+  /**
+   * Per-plugin config namespaces. Reserved top-level key.
+   * Each plugin's config lives at plugins.<id>.*
+   * Plugin-shaped legacy top-level keys (e.g. openspec.*) stay at top-level
+   * until each extract-*-as-plugin change migrates them.
+   */
+  plugins: PluginsConfig;
 }
 
 export interface CorsConfig {
@@ -117,6 +130,7 @@ export interface CorsConfig {
 const VALID_SPAWN_STRATEGIES: SpawnStrategy[] = ["tmux", "headless"];
 
 const DEFAULTS: DashboardConfig = {
+  plugins: {},
   port: 8000,
   piPort: 9999,
   autoStart: true,
@@ -237,6 +251,36 @@ function parseMemoryLimits(raw: any): MemoryLimitsConfig {
   };
 }
 
+function parsePluginsConfig(raw: unknown): PluginsConfig {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const result: PluginsConfig = {};
+  for (const [id, val] of Object.entries(raw as Record<string, unknown>)) {
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      result[id] = val as Record<string, unknown>;
+    }
+  }
+  return result;
+}
+
+/**
+ * Get the plugins config block from a loaded DashboardConfig.
+ * Provides typed access to plugins.<id>.* namespaces.
+ */
+export function getPluginsConfig(config: DashboardConfig): PluginsConfig {
+  return config.plugins ?? {};
+}
+
+/**
+ * Get a single plugin's config from a loaded DashboardConfig.
+ * Returns {} if the plugin has no stored config.
+ */
+export function getPluginConfig(
+  config: DashboardConfig,
+  pluginId: string,
+): Record<string, unknown> {
+  return config.plugins?.[pluginId] ?? {};
+}
+
 function parseKnownServers(raw: any): KnownServer[] {
   if (!Array.isArray(raw)) return [];
   return raw
@@ -299,6 +343,7 @@ export function loadConfig(): DashboardConfig {
       ...(typeof parsed.lastServer === "string" ? { lastServer: parsed.lastServer } : {}),
       electronMode: parsed.electronMode === true,
       knownServers: parseKnownServers(parsed.knownServers),
+      plugins: parsePluginsConfig(parsed.plugins),
     };
 
     // Compute resolvedTrustedNetworks: merge trustedNetworks + auth.bypassHosts

package/packages/shared/src/dashboard-plugin/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Barrel export for dashboard plugin system shared types.
+ * Import from:
+ *   @blackbelt-technology/pi-dashboard-shared/dashboard-plugin/index.js
+ *   @blackbelt-technology/pi-dashboard-shared/dashboard-plugin/slot-types.js
+ *   etc.
+ */
+export * from "./slot-types.js";
+export * from "./manifest-types.js";
+export * from "./slot-props.js";
+export * from "./plugin-status.js";

package/packages/shared/src/dashboard-plugin/manifest-types.ts

@@ -0,0 +1,58 @@
+import type { SlotId, SettingsTab } from "./slot-types.js";
+
+/**
+ * A single slot claim in a plugin manifest.
+ */
+export interface PluginClaim {
+  /** The slot this claim targets. */
+  slot: SlotId;
+  /** Exported component name from the plugin's client entry (for React slots). */
+  component?: string;
+  /** Route command for "command-route" slot (e.g. "/specs"). */
+  command?: string;
+  /** Trigger id for "anchored-popover" slot. */
+  trigger?: string;
+  /** toolName for "tool-renderer" slot. */
+  toolName?: string;
+  /**
+   * For "settings-section" slot: which SettingsPanel tab to render in.
+   * Defaults to "general" if omitted.
+   */
+  tab?: SettingsTab;
+  /** Slot-specific extra config. */
+  config?: Record<string, unknown>;
+  /** Optional exported predicate function name for filtering contributions. */
+  predicate?: string;
+}
+
+/**
+ * The pi-dashboard-plugin manifest.
+ * Declared as the `pi-dashboard-plugin` field in a package.json,
+ * or as a top-level `dashboard-plugin.json` adjacent to package.json.
+ */
+export interface PluginManifest {
+  /** Globally unique kebab-case plugin id. */
+  id: string;
+  /** Human-readable display name. */
+  displayName: string;
+  /**
+   * Lower number = rendered earlier in multi-contribution slots.
+   * Default 1000. First-party plugins use 100.
+   */
+  priority?: number;
+  /** Relative path to the bundled client entry (from package root). */
+  client?: string;
+  /** Optional relative path to the server entry. */
+  server?: string;
+  /** Optional relative path to a pi-extension/bridge entry. */
+  bridge?: string;
+  /** Optional relative path to a JSON Schema 7 file for plugin config validation. */
+  configSchema?: string;
+  /** Slot claims. */
+  claims: PluginClaim[];
+  /**
+   * When true, the plugin is a test fixture and SHALL be excluded from
+   * production bundles (NODE_ENV=production).
+   */
+  fixture?: boolean;
+}

package/packages/shared/src/dashboard-plugin/plugin-status.ts

@@ -0,0 +1,26 @@
+/**
+ * Plugin status types used in /api/health.plugins[] and WebSocket broadcasts.
+ */
+
+/** Status of a single discovered plugin, reported by /api/health. */
+export interface PluginStatus {
+  id: string;
+  enabled: boolean;
+  loaded: boolean;
+  /** Error message if the plugin failed to load or has a conflict. */
+  error?: string;
+  /** Number of slot claims declared in the plugin's manifest. */
+  claims: number;
+}
+
+/** WebSocket broadcast sent to all browsers when a plugin's config changes. */
+export interface PluginConfigUpdate {
+  type: "plugin_config_update";
+  /** Plugin id that was updated. */
+  id: string;
+  /**
+   * Only this plugin's namespace config (plugins.<id>.*).
+   * Never contains other plugins' config.
+   */
+  config: unknown;
+}

package/packages/shared/src/dashboard-plugin/slot-props.ts

@@ -0,0 +1,92 @@
+/**
+ * Typed prop contracts for each slot id.
+ *
+ * Every slot consumer passes exactly the props defined here to each contribution
+ * component. Plugins receive only the props for the slot they claim.
+ *
+ * NOTE: PluginContext is imported as a type-only forward reference so this
+ * shared package doesn't depend on the runtime package. The runtime package
+ * will re-export this map with the concrete PluginContext type filled in.
+ */
+import type { DashboardSession } from "../types.js";
+import type { SlotId } from "./slot-types.js";
+
+/**
+ * Opaque marker type for PluginContext.
+ * The concrete type is defined in @blackbelt-technology/dashboard-plugin-runtime/context.
+ * Using `unknown` here keeps this shared types-only package free of runtime deps.
+ */
+export type AnyPluginContext = unknown;
+
+/** Folder descriptor passed to sidebar-folder-section slot. */
+export interface FolderDescriptor {
+  cwd: string;
+  label?: string;
+}
+
+/** Map of slot id → props type for that slot's contributions. */
+export interface SlotPropsMap {
+  "sidebar-folder-section": {
+    folder: FolderDescriptor;
+    pluginContext: AnyPluginContext;
+  };
+  "session-card-badge": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
+  "session-card-action-bar": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
+  "content-view": {
+    session: DashboardSession;
+    routeParams: Record<string, string>;
+    onClose: () => void;
+    pluginContext: AnyPluginContext;
+  };
+  "content-header-sticky": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
+  "content-inline-footer": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
+  "anchored-popover": {
+    anchorEl: HTMLElement;
+    onDismiss: () => void;
+    pluginContext: AnyPluginContext;
+  };
+  "command-route": {
+    session: DashboardSession;
+    routeParams: Record<string, string>;
+    onClose: () => void;
+    pluginContext: AnyPluginContext;
+  };
+  "settings-section": {
+    pluginContext: AnyPluginContext;
+  };
+  "tool-renderer": {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    sessionId: string;
+    pluginContext: AnyPluginContext;
+  };
+  // Descriptor-only slots don't have React props (consumed by extension-ui-system)
+  "management-modal": Record<string, unknown>;
+  "footer-segment": Record<string, unknown>;
+  "agent-metric": Record<string, unknown>;
+  "breadcrumb": Record<string, unknown>;
+  "gate": Record<string, unknown>;
+  "toast": Record<string, unknown>;
+  "rjsf-form": Record<string, unknown>;
+}
+
+/** Get the props type for a specific slot id. */
+export type SlotProps<S extends SlotId> = SlotPropsMap[S];
+
+// Type-level test: assert SlotPropsMap covers every SlotId.
+// This will produce a TS error if any SlotId is not in SlotPropsMap.
+type _AssertAllSlotsCovered = {
+  [K in SlotId]: SlotPropsMap[K];
+};

package/packages/shared/src/dashboard-plugin/slot-types.ts

@@ -0,0 +1,151 @@
+/**
+ * Frozen slot taxonomy for the dashboard plugin system.
+ * These ids and their payload contracts are versioned via
+ * @blackbelt-technology/pi-dashboard-shared.
+ *
+ * Adding a slot: minor (non-breaking).
+ * Removing or renaming a slot: major (breaking).
+ */
+
+/** All valid slot ids (frozen for v0.x). */
+export type SlotId =
+  // React-only slots
+  | "sidebar-folder-section"
+  | "session-card-action-bar"
+  | "content-inline-footer"
+  | "anchored-popover"
+  | "command-route"
+  | "tool-renderer"
+  // React-or-descriptor slots
+  | "session-card-badge"
+  | "content-view"
+  | "content-header-sticky"
+  | "settings-section"
+  // Descriptor-only slots (from extension-ui-system)
+  | "management-modal"
+  | "footer-segment"
+  | "agent-metric"
+  | "breadcrumb"
+  | "gate"
+  | "toast"
+  | "rjsf-form";
+
+/** How many contributions a slot allows. */
+export type Multiplicity = "one" | "many" | "one-active";
+
+/** Which payload types the slot accepts. */
+export type PayloadTier = "react-only" | "descriptor-only" | "react-or-descriptor";
+
+export interface SlotDefinition {
+  multiplicity: Multiplicity;
+  payloadTier: PayloadTier;
+  description: string;
+}
+
+/** Frozen slot definitions map for v0.x. */
+export const SLOT_DEFINITIONS: Record<SlotId, SlotDefinition> = {
+  "sidebar-folder-section": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Collapsible block above session list per workspace folder",
+  },
+  "session-card-badge": {
+    multiplicity: "many",
+    payloadTier: "react-or-descriptor",
+    description: "Compact info chip on a session card",
+  },
+  "session-card-action-bar": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Action buttons on a session card",
+  },
+  "content-view": {
+    multiplicity: "one-active",
+    payloadTier: "react-or-descriptor",
+    description: "Full-screen content area view for a session",
+  },
+  "content-header-sticky": {
+    multiplicity: "many",
+    payloadTier: "react-or-descriptor",
+    description: "Sticky header above the content view",
+  },
+  "content-inline-footer": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Inline footer below the content view (React-only)",
+  },
+  "anchored-popover": {
+    multiplicity: "one",
+    payloadTier: "react-only",
+    description: "Popover anchored to a UI trigger element",
+  },
+  "command-route": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Maps a slash command or URL route to a content view",
+  },
+  "settings-section": {
+    multiplicity: "many",
+    payloadTier: "react-or-descriptor",
+    description: "A section in the Settings page",
+  },
+  "tool-renderer": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Custom React renderer for a specific tool call by toolName",
+  },
+  // Descriptor-only (extension-ui-system)
+  "management-modal": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Full-screen management modal (extension-ui-system)",
+  },
+  "footer-segment": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Segment in the session footer bar (extension-ui-system)",
+  },
+  "agent-metric": {
+    multiplicity: "one",
+    payloadTier: "descriptor-only",
+    description: "Metric chip on an agent card (extension-ui-system)",
+  },
+  "breadcrumb": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Breadcrumb item in the content header (extension-ui-system)",
+  },
+  "gate": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Flow gate/checkpoint UI (extension-ui-system)",
+  },
+  "toast": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "Transient notification toast (extension-ui-system)",
+  },
+  "rjsf-form": {
+    multiplicity: "many",
+    payloadTier: "descriptor-only",
+    description: "JSON-Schema-driven form (extension-ui-system Phase 4)",
+  },
+};
+
+/** Valid settings tab ids in SettingsPanel. */
+export type SettingsTab =
+  | "general"
+  | "servers"
+  | "packages"
+  | "providers"
+  | "security"
+  | "advanced";
+
+export const VALID_SETTINGS_TABS: SettingsTab[] = [
+  "general",
+  "servers",
+  "packages",
+  "providers",
+  "security",
+  "advanced",
+];

package/packages/shared/src/openspec-activity-detector.ts

@@ -83,29 +83,25 @@ export function detectOpenSpecActivity(
   }
 
   if (tool === "bash") {
-    const command = args.command as string | undefined;
-    if (!command || !command.includes("openspec")) return null;
-
-    // Check for --change flag
-    const flagMatch = command.match(CLI_CHANGE_FLAG_RE);
-    if (flagMatch) {
-      return { changeName: flagMatch[1], isActive: true };
-    }
-
-    // Check for openspec archive <name>
-    const archiveMatch = command.match(CLI_ARCHIVE_RE);
-    if (archiveMatch) {
-      return { changeName: archiveMatch[1], isActive: true };
-    }
-
-    // Check for openspec new change "name"
-    const newChangeMatch = command.match(CLI_NEW_CHANGE_RE);
-    if (newChangeMatch) {
-      return { changeName: newChangeMatch[1], isActive: true };
+      const command = args.command as string | undefined;
+      if (!command || !command.includes("openspec")) return null;
+
+      // Try each CLI regex in order; first match wins.
+      const match =
+        command.match(CLI_CHANGE_FLAG_RE) ??
+        command.match(CLI_ARCHIVE_RE) ??
+        command.match(CLI_NEW_CHANGE_RE);
+      if (!match) return null;
+
+      const name = match[1];
+      // Reject flag-shaped tokens (e.g. `--help`, `-h`). The CLI regex capture
+      // groups use `[^\s"']+` which would otherwise treat `--help` as a change
+      // name and trigger downstream auto-attach + auto-rename.
+      // See change: fix-openspec-flag-rename-bug.
+      if (name.startsWith("-")) return null;
+
+      return { changeName: name, isActive: true };
     }
 
-    return null;
-  }
-
   return null;
 }

package/packages/shared/src/openspec-design-evidence.ts

@@ -0,0 +1,109 @@
+/**
+ * Local-evidence override for the OpenSpec `design` artifact.
+ *
+ * The upstream `spec-driven` schema requires `design.md` as a hard,
+ * single-file dependency of `tasks`. Two real-world workflows fight that:
+ *
+ *   • **Split design** — users put design content in `design-rendering.md`
+ *     + `design-state.md`. The CLI doesn't see them; status reports
+ *     `design: ready` forever; dashboard shows `[Continue] [FF]` instead of
+ *     `[Apply]`.
+ *   • **No-design changes** — trivial fixes that don't need a design doc.
+ *     User writes `tasks.md`, starts implementing; CLI still says
+ *     `design: ready`; dashboard buttons are wrong.
+ *
+ * This module computes a boolean "is design satisfied locally?" from
+ * file-system evidence the CLI ignores. It is consumed by:
+ *
+ *   1. `buildOpenSpecData` in `openspec-poller.ts` — promotes
+ *      `artifacts[design].status` from "ready" to "done" when the rules fire.
+ *      Promote-only; design-only; never demotes; never touches other artifacts.
+ *
+ *   2. `.pi/skills/openspec-shared/scripts/effective-status.sh` — the
+ *      OpenSpec workflow skills invoke this wrapper instead of
+ *      `openspec status --json` so skill-driven prompts and dashboard buttons
+ *      cannot disagree.
+ *
+ * Three rules, evaluated in order with short-circuit:
+ *
+ *   R1  any file matching ^design.*\.md$ exists in the change folder
+ *   R2  a design/ subdirectory exists with at least one *.md inside
+ *   R3  tasks.md exists AND contains at least one Markdown checkbox
+ *       (^\s*-\s+\[[ xX]\]\s)
+ *
+ * R3 is heuristic but defensible: a user who wrote actionable tasks has
+ * already made the design decisions. The schema's hard dependency is
+ * paperwork we don't believe in for trivial changes.
+ *
+ * See change: fix-openspec-design-detection.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+/** Probe surface — kept tiny so unit tests can pass an in-memory stub. */
+export interface DesignEvidenceProbe {
+  /** R1: any file matching `^design.*\.md$` in `changeDir`. */
+  hasDesignFile(changeDir: string): boolean;
+  /** R2: `<changeDir>/design/` exists and contains at least one `*.md`. */
+  hasDesignDirWithMd(changeDir: string): boolean;
+  /** R3: `<changeDir>/tasks.md` contains at least one Markdown checkbox. */
+  tasksHasCheckboxes(changeDir: string): boolean;
+}
+
+/** Pure rule evaluator. R1 → R2 → R3, short-circuits on first match. */
+export function evaluateLocalDesignSatisfaction(
+  changeDir: string,
+  probe: DesignEvidenceProbe,
+): boolean {
+  if (probe.hasDesignFile(changeDir)) return true;
+  if (probe.hasDesignDirWithMd(changeDir)) return true;
+  if (probe.tasksHasCheckboxes(changeDir)) return true;
+  return false;
+}
+
+const DESIGN_FILE_RE = /^design.*\.md$/;
+const CHECKBOX_RE = /^\s*-\s+\[[ xX]\]\s/m;
+
+/** Production probe — backed by the real filesystem. Sync, defensive. */
+export function createFsDesignEvidenceProbe(): DesignEvidenceProbe {
+  return {
+    hasDesignFile(changeDir) {
+      try {
+        const entries = readdirSync(changeDir, { withFileTypes: true });
+        for (const e of entries) {
+          if (e.isFile() && DESIGN_FILE_RE.test(e.name)) return true;
+        }
+        return false;
+      } catch {
+        return false;
+      }
+    },
+
+    hasDesignDirWithMd(changeDir) {
+      const dir = path.join(changeDir, "design");
+      try {
+        const st = statSync(dir);
+        if (!st.isDirectory()) return false;
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const e of entries) {
+          if (e.isFile() && e.name.endsWith(".md")) return true;
+        }
+        return false;
+      } catch {
+        return false;
+      }
+    },
+
+    tasksHasCheckboxes(changeDir) {
+      const tasks = path.join(changeDir, "tasks.md");
+      if (!existsSync(tasks)) return false;
+      try {
+        const text = readFileSync(tasks, "utf8");
+        return CHECKBOX_RE.test(text);
+      } catch {
+        return false;
+      }
+    },
+  };
+}