@f5-sales-demo/xcsh 19.83.0 → 19.84.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.83.0",
+	"version": "19.84.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -56,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.83.0",
-		"@f5-sales-demo/pi-agent-core": "19.83.0",
-		"@f5-sales-demo/pi-ai": "19.83.0",
-		"@f5-sales-demo/pi-natives": "19.83.0",
-		"@f5-sales-demo/pi-resource-management": "19.83.0",
-		"@f5-sales-demo/pi-tui": "19.83.0",
-		"@f5-sales-demo/pi-utils": "19.83.0",
+		"@f5-sales-demo/xcsh-stats": "19.84.0",
+		"@f5-sales-demo/pi-agent-core": "19.84.0",
+		"@f5-sales-demo/pi-ai": "19.84.0",
+		"@f5-sales-demo/pi-natives": "19.84.0",
+		"@f5-sales-demo/pi-resource-management": "19.84.0",
+		"@f5-sales-demo/pi-tui": "19.84.0",
+		"@f5-sales-demo/pi-utils": "19.84.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/office-serve-lifecycle.ts

@@ -0,0 +1,118 @@
+/**
+ * Supersede / recycle a foreground `xcsh office serve`.
+ *
+ * `office serve` binds a FIXED :8444 listener, so after a `brew upgrade` the old
+ * serve squats the port on the stale binary and a fresh `office serve` dies with
+ * "port 8444 in use". These helpers let the new serve step the old one down on
+ * start (supersede), and give `office recycle` (run from brew post_install) a way
+ * to stop the stale serve so the next start is clean — the office analog of
+ * `chrome recycle`.
+ *
+ * Safety: we only ever signal a PID that (a) actually holds :8444 AND (b) looks
+ * like an `office serve` (its `ps` command line contains "office serve"). A
+ * foreign holder is reported, never killed — so PID reuse can't make us signal an
+ * unrelated process.
+ */
+import { OFFICE_PANE_PORT } from "./office-pane-server";
+
+/** Injectable seams so the wait/signal logic is unit-testable without real procs. */
+export interface ServeLifecycleDeps {
+	/** PID listening on `port`, or 0 if none/unknown (best-effort via lsof). */
+	pidListeningOn: (port: number) => number;
+	/** Whether `pid`'s command line is an `xcsh office serve`. */
+	isOfficeServe: (pid: number) => boolean;
+	/** Send a signal to `pid` (process.kill). */
+	signal: (pid: number, sig: NodeJS.Signals) => void;
+	/** Await `ms` (setTimeout in prod; immediate in tests). */
+	sleep: (ms: number) => Promise<void>;
+}
+
+export interface SupersedeResult {
+	/** True when a stale serve was found and stepped down. */
+	superseded: boolean;
+	/** The stale PID we signalled (present only when superseded). */
+	pid?: number;
+}
+
+const WAIT_MS = 3000;
+const POLL_MS = 100;
+
+/** PID listening on `port`, or 0 (best-effort; lsof unavailable → 0). */
+function pidListeningOn(port: number): number {
+	try {
+		const out = Bun.spawnSync(["lsof", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"])
+			.stdout.toString()
+			.trim()
+			.split("\n")[0];
+		const pid = Number(out);
+		return Number.isInteger(pid) && pid > 0 ? pid : 0;
+	} catch {
+		return 0;
+	}
+}
+
+/** Whether `pid`'s full command line is an `xcsh office serve` (ps, best-effort). */
+function isOfficeServe(pid: number): boolean {
+	try {
+		const out = Bun.spawnSync(["ps", "-p", String(pid), "-o", "command="]).stdout.toString();
+		return /office\s+serve/.test(out);
+	} catch {
+		return false;
+	}
+}
+
+const defaultDeps: ServeLifecycleDeps = {
+	pidListeningOn,
+	isOfficeServe,
+	signal: (pid, sig) => process.kill(pid, sig),
+	sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+};
+
+/** SIGTERM `pid` and poll until `port` is released by it, or throw on timeout. */
+async function signalAndWait(pid: number, port: number, deps: ServeLifecycleDeps): Promise<void> {
+	deps.signal(pid, "SIGTERM");
+	for (let waited = 0; waited < WAIT_MS; waited += POLL_MS) {
+		await deps.sleep(POLL_MS);
+		const now = deps.pidListeningOn(port);
+		if (now <= 0 || now !== pid) return; // freed (or a different serve took over)
+	}
+	throw new Error(`Timed out waiting for the stale office serve (PID ${pid}) to release port ${port}.`);
+}
+
+/**
+ * Step down a stale `office serve` holding `port` so a fresh serve can bind.
+ * No-op when the port is free. Throws (without signalling) when the holder is not
+ * an office serve — the caller should surface that rather than kill a stranger.
+ */
+export async function supersedeStaleServe(
+	port = OFFICE_PANE_PORT,
+	deps: ServeLifecycleDeps = defaultDeps,
+): Promise<SupersedeResult> {
+	const pid = deps.pidListeningOn(port);
+	if (pid <= 0 || pid === process.pid) return { superseded: false };
+	if (!deps.isOfficeServe(pid)) {
+		throw new Error(
+			`Port ${port} is held by PID ${pid}, which isn't an xcsh office serve. Stop it manually, then retry.`,
+		);
+	}
+	await signalAndWait(pid, port, deps);
+	return { superseded: true, pid };
+}
+
+/**
+ * Stop a running `office serve` (if any) — used by `office recycle` and brew
+ * post_install so an upgrade clears the stale serve. Returns a human message;
+ * never throws for the ordinary cases (nothing running / foreign holder).
+ */
+export async function recycleOfficeServe(
+	port = OFFICE_PANE_PORT,
+	deps: ServeLifecycleDeps = defaultDeps,
+): Promise<string> {
+	const pid = deps.pidListeningOn(port);
+	if (pid <= 0) return "No xcsh office serve is running.";
+	if (!deps.isOfficeServe(pid)) {
+		return `Port ${port} is held by PID ${pid}, which isn't an xcsh office serve — leaving it alone.`;
+	}
+	await signalAndWait(pid, port, deps);
+	return `Stopped the running office serve (PID ${pid}). Start it again with \`xcsh office serve\`.`;
+}

package/src/cli/office-cli.ts

@@ -13,13 +13,15 @@ import { LOCALIP_HOST } from "../browser/bridge-cert";
 import { type HeadlessChatBridge, startHeadlessChatBridge } from "../browser/headless-bridge";
 import {
 	getOfficePaneDir,
+	OFFICE_PANE_PORT,
 	type OfficePaneServer,
 	readManifest,
 	startOfficePaneServer,
 } from "../browser/office-pane-server";
+import { recycleOfficeServe, supersedeStaleServe } from "../browser/office-serve-lifecycle";
 
 /** The subcommands `xcsh office` accepts (also the Args `options` constraint). */
-export const OFFICE_ACTIONS = ["serve", "manifest", "sideload"] as const;
+export const OFFICE_ACTIONS = ["serve", "manifest", "sideload", "recycle"] as const;
 export type OfficeAction = (typeof OFFICE_ACTIONS)[number];
 
 /** Desktop Office apps a sideload can target. */
@@ -50,9 +52,10 @@ export async function writeManifest(outPath?: string): Promise<string> {
 export interface OfficeServeDeps {
 	startOfficePaneServer: typeof startOfficePaneServer;
 	startHeadlessChatBridge: typeof startHeadlessChatBridge;
+	supersedeStaleServe: typeof supersedeStaleServe;
 }
 
-const defaultServeDeps: OfficeServeDeps = { startOfficePaneServer, startHeadlessChatBridge };
+const defaultServeDeps: OfficeServeDeps = { startOfficePaneServer, startHeadlessChatBridge, supersedeStaleServe };
 
 /** A running `office serve`: the pane file server, the (optional) chat bridge, and
  *  a teardown that disposes both. */
@@ -70,6 +73,14 @@ export interface OfficeServeHandle {
  * Extracted from {@link runServe} so the start/teardown wiring is unit-testable.
  */
 export async function startOfficeServe(deps: OfficeServeDeps = defaultServeDeps): Promise<OfficeServeHandle> {
+	// Step down a stale serve squatting :8444 (e.g. left over from before a
+	// `brew upgrade`) so this start binds cleanly instead of "port 8444 in use".
+	const superseded = await deps.supersedeStaleServe(OFFICE_PANE_PORT);
+	if (superseded.superseded) {
+		console.log(
+			`Superseded a previous office serve (PID ${superseded.pid}) that was holding port ${OFFICE_PANE_PORT}.`,
+		);
+	}
 	const server = await deps.startOfficePaneServer();
 	let chat: HeadlessChatBridge | null = null;
 	try {
@@ -170,5 +181,8 @@ export async function runOfficeCommand(args: OfficeCommandArgs): Promise<void> {
 		case "sideload":
 			await runSideload(args.app ?? "excel");
 			return;
+		case "recycle":
+			console.log(await recycleOfficeServe());
+			return;
 	}
 }

package/src/commands/office.ts

@@ -9,7 +9,7 @@ export default class Office extends Command {
 
 	static args = {
 		action: Args.string({
-			description: "serve | manifest | sideload",
+			description: "serve | manifest | sideload | recycle",
 			required: false,
 			options: OFFICE_ACTIONS,
 		}),
@@ -31,6 +31,7 @@ export default class Office extends Command {
 			console.log("  serve     Start the https://127-0-0-1.local-ip.sh:8444 task-pane listener");
 			console.log("  manifest  Print (or -o write) the add-in manifest.json");
 			console.log("  sideload  Sideload the add-in into a desktop Office app");
+			console.log("  recycle   Stop a running serve (so the next `serve` starts clean after an upgrade)");
 			return;
 		}
 		await runOfficeCommand({

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.83.0",
-	"commit": "a0d8a930a0b6f8bba3730223529fbd078cc06ee9",
-	"shortCommit": "a0d8a93",
+	"version": "19.84.0",
+	"commit": "61adb144f98de4a4989e874a9c8b6641effc3b52",
+	"shortCommit": "61adb14",
 	"branch": "main",
-	"tag": "v19.83.0",
-	"commitDate": "2026-07-23T13:56:27Z",
-	"buildDate": "2026-07-23T14:21:15.547Z",
+	"tag": "v19.84.0",
+	"commitDate": "2026-07-23T14:56:34Z",
+	"buildDate": "2026-07-23T15:21:30.427Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/a0d8a930a0b6f8bba3730223529fbd078cc06ee9",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.83.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/61adb144f98de4a4989e874a9c8b6641effc3b52",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.84.0"
 };