@blackbelt-technology/pi-agent-dashboard 0.2.8 → 0.3.0

package/packages/shared/src/recommended-extensions.ts

@@ -0,0 +1,180 @@
+/**
+ * Recommended pi extensions for pi-agent-dashboard.
+ *
+ * The dashboard has custom UI and wiring for a small set of pi extensions
+ * it was built to work with. This manifest enumerates them so the dashboard
+ * can surface installation status, offer one-click installs in the Packages
+ * tab, walk users through setup in the first-launch wizard, and warn when
+ * a `required` entry is missing.
+ *
+ * This list is intentionally curated (not auto-discovered from npm). Each
+ * entry lives and dies by explicit PR review — the dashboard team owns the
+ * decision of which extensions are promoted.
+ *
+ * Descriptions in `fallbackDescription` are shipped inline. At runtime the
+ * dashboard server optionally enriches them with live descriptions fetched
+ * from the npm registry or GitHub (see `/api/packages/recommended`).
+ */
+
+/** Relative importance of a recommended extension. */
+export type RecommendedExtensionStatus =
+	| "required"            // dashboard features or provider paths break without it
+	| "strongly-suggested"  // dashboard has UI that depends on this
+	| "optional";           // nice-to-have
+
+/** Static manifest entry. Enriched at runtime via the recommended route. */
+export interface RecommendedExtension {
+	/** Stable kebab-case identifier. Used for skip/persist state and IPC. */
+	id: string;
+
+	/**
+	 * pi install source. Any form parseable by pi's DefaultPackageManager:
+	 *   - `npm:<name>`
+	 *   - `git:<host>/<path>`
+	 *   - `git@<host>:<path>.git`
+	 *   - `https://<host>/<path>.git`
+	 *   - local path
+	 */
+	source: string;
+
+	/** Human-readable package name for the UI. */
+	displayName: string;
+
+	/**
+	 * Fallback description. Used when npm/GitHub is unreachable. Kept
+	 * short (one or two sentences).
+	 */
+	fallbackDescription: string;
+
+	/** Relative importance. */
+	status: RecommendedExtensionStatus;
+
+	/** Which dashboard features light up when this is installed. */
+	unlocks: string[];
+
+	/** Tool names this extension registers (for diagnostics / UI hinting). */
+	toolsRegistered?: string[];
+
+	/**
+	 * True when the extension self-wires into pi / dashboard without
+	 * additional configuration — installing it is sufficient for it to
+	 * start working.
+	 */
+	autowired?: boolean;
+}
+
+/** Enriched manifest entry returned by GET /api/packages/recommended. */
+export interface EnrichedRecommendedExtension extends RecommendedExtension {
+	/** Live description (falls back to `fallbackDescription` on fetch failure). */
+	description: string;
+	/** Current upstream version, if available. */
+	version?: string;
+	/**
+	 * Install status by scope. `null` means not present on disk in any scope.
+	 */
+	installed: { scope: "global" | "local" | null };
+	/** True iff the source is currently listed in `~/.pi/agent/settings.json` `packages[]`. */
+	activeInPi: boolean;
+	/** True iff a newer version is available upstream. */
+	updateAvailable: boolean;
+}
+
+export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
+	{
+		id: "pi-anthropic-messages",
+		source: "git@github.com:BlackBeltTechnology/pi-anthropic-messages.git",
+		displayName: "pi-anthropic-messages",
+		fallbackDescription:
+			"Protocol bridge that makes pi's custom tools work with any " +
+			"anthropic-messages endpoint for Claude models (direct Anthropic " +
+			"OAuth/API key, 9Router cc/claude-*, pi-model-proxy, any Claude " +
+			"Code-flavored proxy). Required whenever a provider has " +
+			'api: "anthropic-messages" with a Claude model — without it, ' +
+			"tool calls fall back to Claude Code's built-in bash_ide sandbox.",
+		status: "required",
+		unlocks: ["Tool calls on Anthropic OAuth / 9Router cc/* / proxy providers"],
+		autowired: true,
+	},
+	{
+		id: "tintinweb-pi-subagents",
+		source: "npm:@tintinweb/pi-subagents",
+		displayName: "@tintinweb/pi-subagents",
+		fallbackDescription:
+			"Claude Code-style autonomous sub-agents for pi. Registers " +
+			"the Agent tool and its companions. The dashboard has custom " +
+			"card UI for it.",
+		status: "strongly-suggested",
+		unlocks: [
+			"Agent tool card UI",
+			"Subagent activity badge",
+			"get_subagent_result / steer_subagent renderers",
+		],
+		toolsRegistered: ["Agent", "get_subagent_result", "steer_subagent"],
+		autowired: true,
+	},
+	{
+		id: "pi-flows",
+		source: "git@github.com:BlackBeltTechnology/pi-flows.git",
+		displayName: "pi-flows",
+		fallbackDescription:
+			"Flow engine, dashboard, and orchestration extensions for pi. " +
+			"Powers the dashboard's Flow view, role aliases, and multi-agent " +
+			"orchestration tools.",
+		status: "strongly-suggested",
+		unlocks: [
+			"Flow dashboard",
+			"Role aliases (@planning, @coding, …)",
+			"subagent / flow_write / flow_results / agent_write / ask_user / skill_read / finish tools",
+		],
+		toolsRegistered: [
+			"subagent",
+			"agent_catalog",
+			"agent_write",
+			"flow_write",
+			"flow_results",
+			"skill_read",
+			"ask_user",
+			"finish",
+		],
+		autowired: true,
+	},
+	{
+		id: "pi-web-access",
+		source: "npm:pi-web-access",
+		displayName: "pi-web-access",
+		fallbackDescription:
+			"Web search, URL fetching, GitHub repo cloning, PDF extraction, " +
+			"and YouTube / local video analysis for pi.",
+		status: "strongly-suggested",
+		unlocks: ["web_search", "code_search", "fetch_content", "get_search_content"],
+		toolsRegistered: [
+			"web_search",
+			"code_search",
+			"fetch_content",
+			"get_search_content",
+		],
+	},
+	{
+		id: "pi-agent-browser",
+		source: "npm:pi-agent-browser",
+		displayName: "pi-agent-browser",
+		fallbackDescription:
+			"Browser automation (open, snapshot, click, fill, screenshot) " +
+			"via the agent-browser CLI.",
+		status: "optional",
+		unlocks: ["browser tool (open, snapshot, click, screenshot)"],
+		toolsRegistered: ["browser"],
+	},
+];
+
+/** Retrieve a recommended entry by id, or `undefined`. */
+export function getRecommendedExtension(id: string): RecommendedExtension | undefined {
+	return RECOMMENDED_EXTENSIONS.find((e) => e.id === id);
+}
+
+/** Retrieve all entries with the given status. */
+export function getRecommendedByStatus(
+	status: RecommendedExtensionStatus,
+): readonly RecommendedExtension[] {
+	return RECOMMENDED_EXTENSIONS.filter((e) => e.status === status);
+}

package/packages/shared/src/rest-api.ts

@@ -7,6 +7,11 @@ import type {
   ApiResponse,
 } from "./types.js";
 
+export type { ApiResponse } from "./types.js";
+import type { EnrichedRecommendedExtension } from "./recommended-extensions.js";
+
+export type { EnrichedRecommendedExtension } from "./recommended-extensions.js";
+
 // ── Sessions ────────────────────────────────────────────────────────
 
 export interface ListSessionsQuery {
@@ -63,6 +68,14 @@ export interface BrowseEntry {
   isPi: boolean;
 }
 
+/**
+ * Response shape for `GET /api/browse?path=<dir>&q=<query>`.
+ *
+ * The optional `q` query parameter, when present and non-empty, causes the
+ * server to filter entries by case-insensitive substring on `name` and rank
+ * them (exact → prefix → word-boundary → substring) before the 200-entry cap.
+ * When omitted or whitespace-only, entries are sorted alphabetically.
+ */
 export interface BrowseResult {
   entries: BrowseEntry[];
   parent: string | null;
@@ -71,6 +84,18 @@ export interface BrowseResult {
 
 export type BrowseResponse = ApiResponse<BrowseResult>;
 
+/** Request body for `POST /api/browse/mkdir`. */
+export interface MkdirRequest {
+  parent: string;
+  name: string;
+}
+
+export interface MkdirResult {
+  path: string;
+}
+
+export type MkdirResponse = ApiResponse<MkdirResult>;
+
 // ── Tunnel Status ───────────────────────────────────────────────────
 
 export type TunnelStatus =
@@ -246,6 +271,46 @@ export interface PackageUpdateInfo {
 
 export type CheckUpdatesResponse = ApiResponse<PackageUpdateInfo[]>;
 
+// ── Pi core version check ────────────────────────────────────
+
+/** A core pi ecosystem CLI package (not managed by pi's PackageManager). */
+export interface PiCorePackage {
+  name: string;
+  displayName: string;
+  currentVersion: string;
+  latestVersion: string | null;
+  updateAvailable: boolean;
+  installSource: "global" | "managed";
+}
+
+export interface PiCoreStatus {
+  packages: PiCorePackage[];
+  updatesAvailable: number;
+  lastChecked: string;
+}
+
+export type PiCoreVersionsResponse = ApiResponse<PiCoreStatus>;
+
+/** Request body for POST /api/pi-core/update. Empty packages = update all. */
+export interface PiCoreUpdateRequest {
+  packages?: string[];
+}
+
+/** Result of a single package update. */
+export interface PiCoreUpdateResult {
+  name: string;
+  success: boolean;
+  error?: string;
+}
+
+/** Response from POST /api/pi-core/update (completes synchronously). */
+export interface PiCoreUpdateResponse {
+  results: PiCoreUpdateResult[];
+  sessionsReloaded: number;
+}
+
+export type PiCoreUpdateApiResponse = ApiResponse<PiCoreUpdateResponse>;
+
 // ── Known Servers ─────────────────────────────────────────────
 
 import type { KnownServer } from "./config.js";
@@ -281,3 +346,9 @@ export interface NetworkInterface {
   netmask: string;
   cidr: string;
 }
+
+// ── Recommended extensions ───────────────────────────
+
+export type ListRecommendedExtensionsResponse = ApiResponse<{
+  recommended: EnrichedRecommendedExtension[];
+}>;

package/packages/shared/src/source-matching.ts

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// source-matching — canonical "two source strings refer to the same package"
+// predicate, shared between the server's /api/packages/recommended route
+// and the Electron wizard's bootstrap enricher.
+//
+// Pure string logic, no fs / no pi SDK dependency. Safe to import from any
+// package (shared, server, client, electron).
+//
+// Input sources take one of these forms:
+//
+//   npm:<name>[@<version>]
+//     e.g.  "npm:pi-web-access", "npm:@tintinweb/pi-subagents@0.5.2"
+//
+//   git@<host>:<owner>/<repo>[.git]
+//     e.g.  "git@github.com:BlackBeltTechnology/pi-flows.git"
+//
+//   https://<host>/<owner>/<repo>[.git][#ref]
+//     e.g.  "https://github.com/BlackBeltTechnology/pi-flows.git"
+//
+//   git:<host>/<owner>/<repo>[#ref]
+//     e.g.  "git:github.com/BlackBeltTechnology/pi-flows#main"
+//
+//   any other string (absolute path, relative path, unrecognized URL)
+//     → parsed as kind:"raw" with the literal preserved
+//
+// Matching rules:
+//   - Same kind: exact comparison of the semantically-meaningful parts.
+//   - Cross-kind (git ↔ raw): the raw source's basename (last path
+//     segment, stripped of trailing slash and trailing .git) must equal
+//     the git repo name, case-insensitive. This handles the common case
+//     where a user registered the package via `pi install -l <path>`
+//     instead of by URL and the basename is the repo name.
+// ---------------------------------------------------------------------------
+
+export type SourceKey =
+	| { kind: "npm"; name: string }
+	| { kind: "git"; host: string; owner: string; repo: string }
+	| { kind: "raw"; source: string };
+
+export function parseSourceKey(source: string): SourceKey {
+	const trimmed = source.trim();
+
+	if (trimmed.startsWith("npm:")) {
+		const spec = trimmed.slice(4).trim();
+		// Strip a trailing @version but preserve the scope @ in @scope/name.
+		// If spec starts with @, the SECOND @ (if any) delimits version.
+		let name = spec;
+		if (spec.startsWith("@")) {
+			const idx = spec.indexOf("@", 1);
+			if (idx > 0) name = spec.slice(0, idx);
+		} else {
+			const idx = spec.indexOf("@");
+			if (idx > 0) name = spec.slice(0, idx);
+		}
+		return { kind: "npm", name };
+	}
+
+	const sshMatch = trimmed.match(/^git@([^:]+):([^/]+)\/([^/.]+)(?:\.git)?$/);
+	if (sshMatch) {
+		return { kind: "git", host: sshMatch[1], owner: sshMatch[2], repo: sshMatch[3] };
+	}
+
+	const httpsMatch = trimmed.match(/^https?:\/\/([^/]+)\/([^/]+)\/([^/#.]+)(?:\.git)?(?:#.+)?$/);
+	if (httpsMatch) {
+		return {
+			kind: "git",
+			host: httpsMatch[1],
+			owner: httpsMatch[2],
+			repo: httpsMatch[3],
+		};
+	}
+
+	const gitPrefixMatch = trimmed.match(/^git:([^/]+)\/([^/]+)\/([^/#]+?)(?:\.git)?(?:#.+)?$/);
+	if (gitPrefixMatch) {
+		return {
+			kind: "git",
+			host: gitPrefixMatch[1],
+			owner: gitPrefixMatch[2],
+			repo: gitPrefixMatch[3],
+		};
+	}
+
+	return { kind: "raw", source: trimmed };
+}
+
+/**
+ * Extract the basename (last path segment, .git-stripped) from a raw
+ * source string. Returns lowercase or null.
+ */
+function localPathBasename(src: string): string | null {
+	const stripped = src.replace(/\/+$/, "").replace(/\.git$/, "");
+	const segments = stripped.split(/[\\/]/);
+	const tail = segments[segments.length - 1];
+	return tail ? tail.toLowerCase() : null;
+}
+
+/**
+ * True iff two source strings refer to the same package. See module
+ * header for the full matching rules and rationale.
+ */
+export function sourcesMatch(a: string, b: string): boolean {
+	const ka = parseSourceKey(a);
+	const kb = parseSourceKey(b);
+
+	if (ka.kind === kb.kind) {
+		if (ka.kind === "npm" && kb.kind === "npm") return ka.name === kb.name;
+		if (ka.kind === "git" && kb.kind === "git") {
+			return (
+				ka.host.toLowerCase() === kb.host.toLowerCase() &&
+				ka.owner.toLowerCase() === kb.owner.toLowerCase() &&
+				ka.repo.toLowerCase() === kb.repo.toLowerCase()
+			);
+		}
+		if (ka.kind === "raw" && kb.kind === "raw") return ka.source === kb.source;
+	}
+
+	// Cross-kind: git ↔ raw (local path). Match on repo basename.
+	const gitKey = ka.kind === "git" ? ka : kb.kind === "git" ? kb : null;
+	const rawKey = ka.kind === "raw" ? ka : kb.kind === "raw" ? kb : null;
+	if (gitKey && rawKey) {
+		const basename = localPathBasename(rawKey.source);
+		if (basename && basename === gitKey.repo.toLowerCase()) return true;
+	}
+
+	return false;
+}

package/packages/shared/src/test-support/setup-home.ts

@@ -0,0 +1,74 @@
+/**
+ * Vitest globalSetup: tripwire + directory bootstrap.
+ *
+ * Wired via `test.globalSetup` in each package's `vitest.config.ts`. Runs ONCE
+ * at vitest boot, before any test file is loaded.
+ *
+ * Responsibilities:
+ *   1. Tripwire — throws if `process.env.HOME` still points at the developer's
+ *      real user home (meaning the root `npm test` script wasn't used and HOME
+ *      wasn't overridden). Aborts the entire run before any destructive code
+ *      can touch real ~/.pi/.
+ *   2. Pre-create `<HOME>/.pi/agent/sessions/` and `<HOME>/.pi/dashboard/` so
+ *      production code that reads those paths finds empty but well-formed
+ *      directories.
+ *
+ * Why globalSetup (not setupFiles):
+ *   setupFiles' `beforeAll` can run AFTER a test file's top-level imports
+ *   execute destructive module-level code. globalSetup runs strictly before
+ *   ANY test file is loaded. Combined with the `npm test` process-level HOME
+ *   override, there is zero window in which code can see real HOME.
+ *
+ * The process-level HOME override in package.json is the primary isolation
+ * layer; this module is the second-line tripwire that catches regressions.
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+
+/** Vitest globalSetup default export. Returns a teardown function. */
+export default function setup() {
+  const currentHome = process.env.HOME ?? "";
+  const realHome = os.userInfo().homedir;
+
+  if (!currentHome) {
+    throw new Error(
+      "[test-isolation] process.env.HOME is empty. " +
+        "Run tests via `npm test` (which sets HOME to a tmp dir) " +
+        "or prefix manually: `HOME=$(mktemp -d) npx vitest run`.",
+    );
+  }
+
+  if (currentHome === realHome) {
+    throw new Error(
+      `[test-isolation] process.env.HOME (${currentHome}) equals the real user home ` +
+        `(${realHome}). This would let tests read and mutate ~/.pi/, potentially killing ` +
+        `live pi sessions. Run tests via \`npm test\` — it sets HOME to an ephemeral tmp dir. ` +
+        `If you invoked vitest directly, prefix with \`HOME=$(mktemp -d)\`.`,
+    );
+  }
+
+  if (!currentHome.startsWith(os.tmpdir())) {
+    // Not strictly fatal — developer may have pointed HOME at a custom scratch dir —
+    // but warn loudly because it's unusual.
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[test-isolation] HOME (${currentHome}) is not under os.tmpdir() (${os.tmpdir()}). ` +
+        `Tests will still run but this layout is unusual.`,
+    );
+  }
+
+  // Pre-create expected .pi subdirectories so code that reads them finds empty dirs.
+  mkdirSync(join(currentHome, ".pi", "agent", "sessions"), { recursive: true });
+  mkdirSync(join(currentHome, ".pi", "dashboard"), { recursive: true });
+
+  // eslint-disable-next-line no-console
+  console.log(`[test-isolation] HOME=${currentHome} (real=${realHome})`);
+
+  // Teardown: nothing to do. The tmp HOME was created by the npm script's
+  // `$(mktemp -d)`; leaving the dir on disk is fine (OS cleans tmpdir).
+  // Tests that need per-file isolation continue to use their own mkdtemp.
+  return () => {
+    /* no-op */
+  };
+}

package/packages/shared/src/types.ts

@@ -140,6 +140,13 @@ export interface OpenSpecChange {
   completedTasks: number;
   totalTasks: number;
   artifacts: OpenSpecArtifact[];
+  /**
+   * Artifact-authoring completeness reported by `openspec status --change <name> --json`.
+   * `true` when all required artifacts for the change's workflow are present/done.
+   * Orthogonal to task-tally completeness; used by the dashboard to surface an
+   * "Archive anyway" escape hatch when artifacts are authored but tasks remain unchecked.
+   */
+  isComplete?: boolean;
 }
 
 /** Lifecycle state of an OpenSpec change, derived from artifacts + task status */