@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.2

package/packages/server/src/browser-gateway.ts

@@ -5,6 +5,7 @@
 import { WebSocketServer, WebSocket } from "ws";
 import type {
   ServerToBrowserMessage,
+  BrowserOpenSpecUpdateMessage,
   BrowserToServerMessage,
 } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
 import type { SessionManager } from "./memory-session-manager.js";
@@ -15,7 +16,7 @@ import { createHeadlessPidRegistry, type HeadlessPidRegistry } from "./headless-
 import type { PendingForkRegistry } from "./pending-fork-registry.js";
 import type { SessionOrderManager } from "./session-order-manager.js";
 import type { PreferencesStore } from "./preferences-store.js";
-import { hasOpenSpecDir, type DirectoryService } from "./directory-service.js";
+import { hasOpenSpecDir, hasOpenSpecRoot, type DirectoryService } from "./directory-service.js";
 
 /**
  * Pure helper: build the per-cwd `openspec_update` messages a freshly
@@ -31,23 +32,30 @@ import { hasOpenSpecDir, type DirectoryService } from "./directory-service.js";
 export function buildOpenSpecConnectSnapshot(
   directoryService: Pick<DirectoryService, "knownDirectories" | "getOpenSpecData">,
   hasDir: (cwd: string) => boolean,
-): Array<ServerToBrowserMessage> {
-  const out: Array<ServerToBrowserMessage> = [];
+  hasRoot: (cwd: string) => boolean = hasDir,
+): Array<BrowserOpenSpecUpdateMessage> {
+  const out: Array<BrowserOpenSpecUpdateMessage> = [];
   for (const cwd of directoryService.knownDirectories()) {
     const cached = directoryService.getOpenSpecData(cwd);
+    const root = hasRoot(cwd);
     if (cached && cached.initialized) {
-      out.push({ type: "openspec_update", cwd, data: cached });
+      // Cached payload already carries `hasOpenspecDir` set by `pollOne`; if
+      // an old cache entry predates that field, fill it from the live probe.
+      const data = cached.hasOpenspecDir === undefined
+        ? { ...cached, hasOpenspecDir: root }
+        : cached;
+      out.push({ type: "openspec_update", cwd, data });
     } else if (hasDir(cwd)) {
       out.push({
         type: "openspec_update",
         cwd,
-        data: { initialized: false, pending: true, changes: [] },
+        data: { initialized: false, pending: true, changes: [], hasOpenspecDir: root },
       });
     } else {
       out.push({
         type: "openspec_update",
         cwd,
-        data: { initialized: false, pending: false, changes: [] },
+        data: { initialized: false, pending: false, changes: [], hasOpenspecDir: root },
       });
     }
   }
@@ -68,7 +76,7 @@ import { handlePinDirectory, handleUnpinDirectory, handleReorderPinnedDirs, hand
 export interface BrowserGateway {
   wss: WebSocketServer;
   broadcastEvent(sessionId: string, seq: number, event: any): void;
-  broadcastSessionAdded(session: any): void;
+  broadcastSessionAdded(session: any, opts?: { spawnRequestId?: string }): void;
   broadcastSessionUpdated(sessionId: string, updates: any): void;
   broadcastSessionRemoved(sessionId: string): void;
   sendToSubscribers(sessionId: string, msg: ServerToBrowserMessage): void;
@@ -119,6 +127,7 @@ export function createBrowserGateway(
   maxWsBufferBytes?: number,
   pendingAttachRegistry?: import("./pending-attach-registry.js").PendingAttachRegistry,
   pendingResumeIntents?: import("./pending-resume-intent-registry.js").PendingResumeIntentRegistry,
+  pendingClientCorrelations?: import("./pending-client-correlations.js").PendingClientCorrelations,
 ): BrowserGateway {
   const wss = new WebSocketServer({ noServer: true });
 
@@ -271,7 +280,7 @@ export function createBrowserGateway(
     // `openspec_update` per cwd, never silently omit.
     // See change: fix-cold-boot-openspec-protocol.
     if (directoryService) {
-      for (const msg of buildOpenSpecConnectSnapshot(directoryService, hasOpenSpecDir)) {
+      for (const msg of buildOpenSpecConnectSnapshot(directoryService, hasOpenSpecDir, hasOpenSpecRoot)) {
         sendTo(ws, msg);
       }
     }
@@ -307,6 +316,7 @@ export function createBrowserGateway(
           headlessPidRegistry, pendingResumeRegistry, pendingDashboardSpawns,
           pendingAttachRegistry,
           pendingResumeIntents,
+          pendingClientCorrelations,
           sendTo, broadcast, getSubscribers, replayPendingUiRequests,
           trackUiRequest: trackUiRequest,
           markReplaying(targetWs, sessionId) {
@@ -574,8 +584,15 @@ export function createBrowserGateway(
       }
     },
 
-    broadcastSessionAdded(session: any) {
-      broadcast({ type: "session_added", session });
+    broadcastSessionAdded(session: any, opts?: { spawnRequestId?: string }) {
+      // Carry the originating client `requestId` (when known) so the
+      // browser can auto-select / dismiss its placeholder by exact
+      // correlation. See change: spawn-correlation-token.
+      broadcast({
+        type: "session_added",
+        session,
+        ...(opts?.spawnRequestId ? { spawnRequestId: opts.spawnRequestId } : {}),
+      });
     },
 
     broadcastSessionUpdated(sessionId: string, updates: any) {

package/packages/server/src/browser-handlers/handler-context.ts

@@ -16,6 +16,7 @@ import type { HeadlessPidRegistry } from "../headless-pid-registry.js";
 import type { PendingResumeRegistry } from "../pending-resume-registry.js";
 import type { PendingAttachRegistry } from "../pending-attach-registry.js";
 import type { PendingResumeIntentRegistry } from "../pending-resume-intent-registry.js";
+import type { PendingClientCorrelations } from "../pending-client-correlations.js";
 
 export interface BrowserHandlerContext {
   ws: WebSocket;
@@ -43,6 +44,14 @@ export interface BrowserHandlerContext {
    * See change: preserve-session-order-on-reboot.
    */
   pendingResumeIntents?: PendingResumeIntentRegistry;
+  /**
+   * Optional registry mapping `spawnToken → requestId` for client-side
+   * correlation. When set, browser-initiated spawns/resumes that carry a
+   * `requestId` are recorded so the eventual `session_added` broadcast
+   * carries `spawnRequestId` for auto-select / placeholder dismissal.
+   * See change: spawn-correlation-token.
+   */
+  pendingClientCorrelations?: PendingClientCorrelations;
   /** Send message to a specific WebSocket */
   sendTo(ws: WebSocket, msg: ServerToBrowserMessage): void;
   /** Broadcast to all connected browsers */

package/packages/server/src/browser-handlers/session-action-handler.ts

@@ -1,6 +1,7 @@
 /**
  * Session action handlers: send_prompt, abort, resume, spawn, shutdown, flow_control.
  */
+import { existsSync } from "node:fs";
 import type { BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
 import type { BrowserHandlerContext } from "./handler-context.js";
 import { spawnPiSession } from "../process-manager.js";
@@ -18,6 +19,20 @@ import {
   findPidByMarker,
 } from "@blackbelt-technology/pi-dashboard-shared/platform/process-identify.js";
 import { shouldInterceptReload } from "./session-action-helpers.js";
+import { keeperOptsFromSpawnResult } from "../headless-pid-registry.js";
+
+/**
+ * Status message + code emitted when fork is attempted on a session whose
+ * `.jsonl` does not exist on disk yet (empty session, no persisted entries).
+ * The dashboard silently degrades to a fresh spawn in the same cwd — fork
+ * has no history to copy, so the user-meaningful semantic of "fork" and
+ * "new" is identical here. The structured code lets the client surface a
+ * non-blocking toast.
+ * See change: fix-fork-empty-session-silent-timeout.
+ */
+export const FORK_DEGRADED_TO_NEW_MESSAGE =
+  "Started a fresh session \u2014 the source had no persisted history to fork from.";
+export const FORK_DEGRADED_TO_NEW_CODE = "FORK_DEGRADED_TO_NEW";
 
 /**
  * Find headless pi PIDs associated with a session-id marker and kill them.
@@ -162,7 +177,13 @@ export async function handleHeadlessReload(
   }
 
   if (spawnResult.pid && spawnResult.process) {
-    headlessPidRegistry.register(spawnResult.pid, session.cwd, spawnResult.process);
+    headlessPidRegistry.register(
+      spawnResult.pid,
+      session.cwd,
+      spawnResult.process,
+      spawnResult.spawnToken,
+      keeperOptsFromSpawnResult(spawnResult),
+    );
   }
 
   emitCommandFeedback(ctx, msg.sessionId, "completed");
@@ -221,7 +242,13 @@ export async function handleSendPrompt(
       pendingDashboardSpawns?.set(promptSession.cwd, (pendingDashboardSpawns?.get(promptSession.cwd) ?? 0) + 1);
     }
     if (spawnResult.process && spawnResult.pid) {
-      headlessPidRegistry.register(spawnResult.pid, promptSession.cwd, spawnResult.process);
+      headlessPidRegistry.register(
+        spawnResult.pid,
+        promptSession.cwd,
+        spawnResult.process,
+        spawnResult.spawnToken,
+        keeperOptsFromSpawnResult(spawnResult),
+      );
     }
   } else {
     const sent = piGateway.sendToSession(msg.sessionId, {
@@ -240,10 +267,10 @@ export async function handleResumeSession(
   msg: Extract<BrowserToServerMessage, { type: "resume_session" }>,
   ctx: BrowserHandlerContext,
 ): Promise<void> {
-  const { ws, sessionManager, pendingForkRegistry, headlessPidRegistry, pendingDashboardSpawns, pendingResumeIntents, sendTo } = ctx;
+  const { ws, sessionManager, pendingForkRegistry, headlessPidRegistry, pendingDashboardSpawns, pendingResumeIntents, pendingClientCorrelations, sendTo } = ctx;
   const session = sessionManager.get(msg.sessionId);
   if (!session) {
-    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session not found" });
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session not found", requestId: msg.requestId });
     return;
   }
   // Resolve placement intent. Old browsers omit the field; default to
@@ -252,28 +279,72 @@ export async function handleResumeSession(
   // See change: differentiate-resume-intent-by-trigger.
   const placement: "front" | "keep" = msg.placement ?? "front";
   if (!session.sessionFile) {
-    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session file is unknown (pre-migration session)" });
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session file is unknown (pre-migration session)", requestId: msg.requestId });
     return;
   }
   if (msg.mode === "continue" && session.status !== "ended") {
-    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already active" });
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already active", requestId: msg.requestId });
     return;
   }
   if (session.resuming) {
-    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already being resumed" });
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already being resumed", requestId: msg.requestId });
     return;
   }
-  if (msg.mode === "fork" && pendingForkRegistry) {
-    pendingForkRegistry.recordFork(session.cwd, msg.sessionId);
+  // Fork preflight: silent-degrade when the source session has no on-disk
+  // JSONL yet (empty session, no persisted entries). `pi --fork <missing>`
+  // would crash silently and produce a 30s register-timeout; instead we
+  // spawn a fresh pi in the same cwd and surface `code: FORK_DEGRADED_TO_NEW`
+  // so the client can render a non-blocking toast. The parent's
+  // attachedProposal (if any) is inherited via `pendingAttachRegistry`
+  // since fork's own inheritance path doesn't run on this branch.
+  // See change: fix-fork-empty-session-silent-timeout.
+  if (msg.mode === "fork" && session.sessionFile && !existsSync(session.sessionFile)) {
+    // Inherit attachedProposal from parent so the new session still
+    // tracks the change the user was working on.
+    const pendingAttachRegistry = ctx.pendingAttachRegistry;
+    if (session.attachedProposal && pendingAttachRegistry) {
+      pendingAttachRegistry.enqueue(session.cwd, session.attachedProposal);
+    }
+    const degradeConfig = loadConfig();
+    // Fresh spawn: no sessionFile, no mode — just `pi --mode rpc`.
+    const degradeResult = await spawnPiSession(session.cwd, {
+      strategy: degradeConfig.spawnStrategy,
+    });
+    if (degradeResult.process && degradeResult.pid) {
+      headlessPidRegistry.register(
+        degradeResult.pid,
+        session.cwd,
+        degradeResult.process,
+        degradeResult.spawnToken,
+        keeperOptsFromSpawnResult(degradeResult),
+      );
+    }
+    if (msg.requestId && degradeResult.spawnToken && pendingClientCorrelations) {
+      pendingClientCorrelations.record(degradeResult.spawnToken, msg.requestId);
+    }
+    if (degradeResult.dashboardSpawned && degradeResult.success) {
+      pendingDashboardSpawns?.set(
+        session.cwd,
+        (pendingDashboardSpawns?.get(session.cwd) ?? 0) + 1,
+      );
+    }
+    sendTo(ws, {
+      type: "resume_result",
+      sessionId: msg.sessionId,
+      success: degradeResult.success,
+      message: degradeResult.success ? FORK_DEGRADED_TO_NEW_MESSAGE : degradeResult.message,
+      requestId: msg.requestId,
+      ...(degradeResult.success ? { code: FORK_DEGRADED_TO_NEW_CODE } : {}),
+    });
+    return;
   }
-
   // For fork-from-message: create a pruned session file first
   let forkSessionFile = session.sessionFile;
   if (msg.mode === "fork" && msg.entryId) {
     try {
       forkSessionFile = createBranchedSessionFile(session.sessionFile, msg.entryId);
     } catch (err: any) {
-      sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: `Fork from entry failed: ${err.message}` });
+      sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: `Fork from entry failed: ${err.message}`, requestId: msg.requestId });
       return;
     }
   }
@@ -293,26 +364,45 @@ export async function handleResumeSession(
     mode: msg.mode,
     strategy: resumeConfig.spawnStrategy,
   });
+  // Record fork parent keyed by spawn token (was: keyed by cwd, racy on
+  // multi-fork-in-same-cwd). See change: spawn-correlation-token.
+  if (msg.mode === "fork" && pendingForkRegistry && result.spawnToken) {
+    pendingForkRegistry.recordFork(result.spawnToken, msg.sessionId);
+  }
+  // Record client-correlation so the eventual session_added carries
+  // spawnRequestId. See change: spawn-correlation-token.
+  if (msg.requestId && result.spawnToken && pendingClientCorrelations) {
+    pendingClientCorrelations.record(result.spawnToken, msg.requestId);
+  }
   if (result.dashboardSpawned && result.success) {
     pendingDashboardSpawns?.set(session.cwd, (pendingDashboardSpawns?.get(session.cwd) ?? 0) + 1);
   }
   if (result.process && result.pid) {
-    headlessPidRegistry.register(result.pid, session.cwd, result.process);
+    headlessPidRegistry.register(
+      result.pid,
+      session.cwd,
+      result.process,
+      result.spawnToken,
+      keeperOptsFromSpawnResult(result),
+    );
   }
-  sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: result.success, message: result.message });
+  sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: result.success, message: result.message, requestId: msg.requestId });
 }
 
 export async function handleSpawnSession(
   msg: Extract<BrowserToServerMessage, { type: "spawn_session" }>,
   ctx: BrowserHandlerContext,
 ): Promise<void> {
-  const { ws, headlessPidRegistry, pendingDashboardSpawns, pendingAttachRegistry, sendTo } = ctx;
+  const { ws, headlessPidRegistry, pendingDashboardSpawns, pendingAttachRegistry, pendingClientCorrelations, sendTo } = ctx;
   const config = loadConfig();
   const strategy = config.spawnStrategy ?? "tmux";
 
   // Queue the optional attach intent BEFORE awaiting the spawn so a fast
   // bridge `session_register` cannot lose the intent. See change:
-  // add-folder-task-checker-and-spawn-attach.
+  // add-folder-task-checker-and-spawn-attach. NOTE: at this point we don't
+  // yet have a spawnToken (spawn hasn't run); we enqueue by cwd-FIFO and
+  // re-record by token after spawnPiSession returns. See change:
+  // spawn-correlation-token.
   if (typeof msg.attachProposal === "string" && msg.attachProposal.length > 0) {
     pendingAttachRegistry?.enqueue(msg.cwd, msg.attachProposal);
   }
@@ -322,7 +412,7 @@ export async function handleSpawnSession(
   const preflight = preflightSpawn(msg.cwd, { resolver: preflightResolver });
   if (!preflight.ok) {
     const message = preflight.reasons.map((r) => r.message).join("; ");
-    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: false, message });
+    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: false, message, requestId: msg.requestId });
     sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message, code: "PREFLIGHT_FAILED", reasons: preflight.reasons });
     appendSpawnFailure({
       ts: new Date().toISOString(),
@@ -342,12 +432,30 @@ export async function handleSpawnSession(
   try {
     const spawnResult = await spawnPiSession(msg.cwd, { strategy });
     if (spawnResult.process && spawnResult.pid) {
-      headlessPidRegistry.register(spawnResult.pid, msg.cwd, spawnResult.process);
+      headlessPidRegistry.register(
+        spawnResult.pid,
+        msg.cwd,
+        spawnResult.process,
+        spawnResult.spawnToken,
+        keeperOptsFromSpawnResult(spawnResult),
+      );
+    }
+    // Record client-correlation so the eventual session_added carries
+    // spawnRequestId. See change: spawn-correlation-token.
+    if (msg.requestId && spawnResult.spawnToken && pendingClientCorrelations) {
+      pendingClientCorrelations.record(spawnResult.spawnToken, msg.requestId);
     }
     if (spawnResult.dashboardSpawned && spawnResult.success) {
       pendingDashboardSpawns?.set(msg.cwd, (pendingDashboardSpawns?.get(msg.cwd) ?? 0) + 1);
     }
-    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: spawnResult.success, message: spawnResult.message });
+    sendTo(ws, {
+      type: "spawn_result",
+      cwd: msg.cwd,
+      success: spawnResult.success,
+      message: spawnResult.message,
+      requestId: msg.requestId,
+      ...(spawnResult.pid ? { pid: spawnResult.pid } : {}),
+    });
     if (!spawnResult.success) {
       sendTo(ws, {
         type: "spawn_error",
@@ -377,12 +485,13 @@ export async function handleSpawnSession(
         // on the next spawn without a server restart. See change: spawn-failure-diagnostics (fix W1).
         timeoutMs: config.spawnRegisterTimeoutMs,
         ws,
+        spawnToken: spawnResult.spawnToken,
       });
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const stderr = err instanceof Error && "stderr" in err ? String((err as { stderr: unknown }).stderr).slice(-2048) : undefined;
-    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: false, message });
+    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: false, message, requestId: msg.requestId });
     sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message, code: "SPAWN_ERRNO", stderr });
     appendSpawnFailure({
       ts: new Date().toISOString(),

package/packages/server/src/changelog-fs.ts

@@ -0,0 +1,167 @@
+/**
+ * Filesystem helpers for locating an installed package's
+ * `CHANGELOG.md` and `package.json`, plus deriving a public GitHub
+ * URL from the `repository` field.
+ *
+ * Search order matches the ToolRegistry resolution chain for `pi`:
+ *   1. Managed install (`~/.pi-dashboard/node_modules/<pkg>/`)
+ *   2. Bare-import via `createRequire` (process resolves the package
+ *      through its own node_modules — covers npm-global on Unix when
+ *      the symlink lands inside this Node prefix, and dev-checkout
+ *      paths during local builds).
+ *
+ * Both helpers return `null` rather than throwing on absence so route
+ * handlers can degrade to the empty-changelog response per spec
+ * `pi-changelog-display#Scenario: Package not installed returns empty`.
+ *
+ * See change: pi-update-whats-new-panel.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createRequire } from "node:module";
+
+/** Default managed install root. Test seam: caller may override. */
+function defaultManagedDir(): string {
+  return path.join(os.homedir(), ".pi-dashboard");
+}
+
+/**
+ * Locate a package's CHANGELOG.md on disk.
+ *
+ * Returns `{ changelogPath, packageDir }` so callers can read the
+ * adjacent `package.json` without re-resolving.
+ *
+ * Strategy:
+ *   1. `<managedDir>/node_modules/<pkg>/CHANGELOG.md` (Electron + CLI bootstrap).
+ *   2. `createRequire(import.meta.url).resolve("<pkg>/package.json")` then
+ *      look for `CHANGELOG.md` next to it (covers bare-import / npm-global
+ *      via the standard Node resolution mechanism).
+ *
+ * Returns `null` when no readable CHANGELOG can be located.
+ */
+export interface ChangelogLocation {
+  changelogPath: string;
+  packageDir: string;
+}
+
+export interface FindOptions {
+  /** Override managed dir for tests. */
+  managedDir?: string;
+  /**
+   * Override the require-resolver used for bare-import lookup. Tests
+   * pass a stub that throws to force the managed path; production
+   * uses `createRequire(import.meta.url).resolve`.
+   */
+  resolveBareImport?: (pkgJsonSpec: string) => string;
+}
+
+export function findChangelogPath(
+  pkg: string,
+  opts: FindOptions = {},
+): ChangelogLocation | null {
+  // Strategy 1: managed install.
+  const managedDir = opts.managedDir ?? defaultManagedDir();
+  const managedPkg = path.join(managedDir, "node_modules", pkg);
+  const managedCl = path.join(managedPkg, "CHANGELOG.md");
+  if (fs.existsSync(managedCl)) {
+    return { changelogPath: managedCl, packageDir: managedPkg };
+  }
+
+  // Strategy 2: bare-import via require.resolve.
+  const resolver =
+    opts.resolveBareImport ??
+    ((spec: string) => createRequire(import.meta.url).resolve(spec));
+  try {
+    const pkgJsonPath = resolver(`${pkg}/package.json`);
+    const dir = path.dirname(pkgJsonPath);
+    const cl = path.join(dir, "CHANGELOG.md");
+    if (fs.existsSync(cl)) {
+      return { changelogPath: cl, packageDir: dir };
+    }
+  } catch {
+    /* not resolvable — fall through */
+  }
+
+  return null;
+}
+
+/**
+ * Read and parse `package.json` next to a previously-located
+ * CHANGELOG. Returns the parsed object or `null` on read/parse error.
+ */
+export function readPackageJson(packageDir: string): Record<string, unknown> | null {
+  const p = path.join(packageDir, "package.json");
+  try {
+    const raw = fs.readFileSync(p, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") {
+      return parsed as Record<string, unknown>;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derive a public GitHub URL pointing at the CHANGELOG given a
+ * `package.json#repository` field. Returns `null` when the field is
+ * missing, not GitHub-hosted, or unparseable.
+ *
+ * Accepted shapes (per spec `pi-changelog-display#Requirement: Changelog URL derivation`):
+ *   - `"github:org/repo"` shorthand
+ *   - `"https://github.com/org/repo.git"` URL string
+ *   - `{ "type": "git", "url": "git+https://github.com/org/repo.git" }`
+ *   - same object form with optional `"directory": "packages/foo"` (monorepo)
+ */
+export function deriveChangelogUrl(repository: unknown): string | null {
+  if (!repository) return null;
+
+  let urlStr: string | null = null;
+  let directory: string | null = null;
+
+  if (typeof repository === "string") {
+    urlStr = repository;
+  } else if (typeof repository === "object" && repository !== null) {
+    const rec = repository as Record<string, unknown>;
+    if (typeof rec.url === "string") urlStr = rec.url;
+    if (typeof rec.directory === "string" && rec.directory.length > 0) {
+      directory = rec.directory.replace(/^\/+|\/+$/g, "");
+    }
+  }
+  if (!urlStr) return null;
+
+  const m = parseGitHubUrl(urlStr);
+  if (!m) return null;
+
+  const subPath = directory ? `${directory}/` : "";
+  return `https://github.com/${m.org}/${m.repo}/blob/main/${subPath}CHANGELOG.md`;
+}
+
+/**
+ * Parse the various GitHub URL forms used in `package.json#repository`
+ * into `{ org, repo }`. Returns null for non-GitHub or unparseable
+ * inputs.
+ */
+function parseGitHubUrl(s: string): { org: string; repo: string } | null {
+  const trimmed = s.trim();
+
+  // github:org/repo shorthand
+  let m = trimmed.match(/^github:([^/]+)\/([^/#]+)/i);
+  if (m) return { org: m[1], repo: stripGitSuffix(m[2]) };
+
+  // git+https://github.com/org/repo.git
+  // https://github.com/org/repo
+  // git://github.com/org/repo.git
+  // ssh://git@github.com/org/repo.git
+  // git@github.com:org/repo.git
+  m = trimmed.match(/(?:^|[/@:])github\.com[/:]([^/]+)\/([^/#?]+)/i);
+  if (m) return { org: m[1], repo: stripGitSuffix(m[2]) };
+
+  return null;
+}
+
+function stripGitSuffix(repo: string): string {
+  return repo.replace(/\.git$/i, "");
+}