@f5-sales-demo/xcsh 19.65.0 → 19.66.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.65.0",
+	"version": "19.66.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -31,7 +31,7 @@
 		"xcsh": "src/cli.ts"
 	},
 	"scripts": {
-		"build": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && bun run generate-console-catalog && bun run generate-console-field-metadata && test -f src/internal-urls/api-spec-index.generated.ts && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset",
+		"build": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && bun run generate-console-catalog && bun run generate-console-field-metadata && test -f src/internal-urls/api-spec-index.generated.ts && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../office-pane scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset && bun --cwd=../office-pane scripts/generate-client-bundle.ts --reset",
 		"check": "biome check . && bun run format-prompts -- --check && bun run check:types",
 		"check:types": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
@@ -56,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.65.0",
-		"@f5-sales-demo/pi-agent-core": "19.65.0",
-		"@f5-sales-demo/pi-ai": "19.65.0",
-		"@f5-sales-demo/pi-natives": "19.65.0",
-		"@f5-sales-demo/pi-resource-management": "19.65.0",
-		"@f5-sales-demo/pi-tui": "19.65.0",
-		"@f5-sales-demo/pi-utils": "19.65.0",
+		"@f5-sales-demo/xcsh-stats": "19.66.1",
+		"@f5-sales-demo/pi-agent-core": "19.66.1",
+		"@f5-sales-demo/pi-ai": "19.66.1",
+		"@f5-sales-demo/pi-natives": "19.66.1",
+		"@f5-sales-demo/pi-resource-management": "19.66.1",
+		"@f5-sales-demo/pi-tui": "19.66.1",
+		"@f5-sales-demo/pi-utils": "19.66.1",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/office-pane-server.ts

@@ -0,0 +1,183 @@
+/**
+ * Static HTTPS listener for the embedded Office task pane.
+ *
+ * Serves the add-in's page shell + JS bundle + unified manifest + ribbon/app
+ * icons over a FIXED `https://127-0-0-1.local-ip.sh:8444` origin — the exact URL
+ * the manifest's `code.page` and ribbon icon URLs point at. TLS terminates with
+ * the SAME publicly-trusted `*.local-ip.sh` cert the `wss` extension bridge uses
+ * (via {@link resolveBridgeTls}), so Office's WebView loads the page with real
+ * TLS verification and no local trust / MDM step.
+ *
+ * This listener is SEPARATE from the extension bridge and serves ONLY static GET
+ * requests (no WebSocket). It never auto-starts — it is launched exclusively by
+ * `xcsh office serve`, keeping blast radius zero.
+ *
+ * Compiled vs dev (Option A — the pane is a build-time embedded asset of the
+ * binary, not a published library):
+ *  - COMPILED: the base64 tar.gz baked into `office-pane.generated.txt` is
+ *    extracted (once, path-traversal-guarded) to `os.tmpdir()/xcsh-office-pane/<hash>`.
+ *  - DEV: assets are read straight from `packages/office-pane/dist` via a
+ *    filesystem path — never a module import, so no dependency on the private
+ *    office-pane package is introduced.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { LOCALIP_HOST, resolveBridgeTls } from "./bridge-cert";
+import embeddedPaneArchiveTxt from "./office-pane.generated.txt";
+
+/** Fixed listener port — must match the manifest page + ribbon icon URLs. */
+export const OFFICE_PANE_PORT = 8444;
+/** Bind loopback only; the local-ip.sh SAN host resolves here for the WebView. */
+export const OFFICE_PANE_HOSTNAME = "127.0.0.1";
+/** The trusted-origin base URL the task pane is reachable at. */
+export const OFFICE_PANE_URL = `https://${LOCALIP_HOST}:${OFFICE_PANE_PORT}`;
+/** The task-pane page URL (the manifest `code.page`). */
+export const OFFICE_PANE_TASKPANE_URL = `${OFFICE_PANE_URL}/taskpane.html`;
+
+const IS_BUN_COMPILED =
+	Bun.env.PI_COMPILED ||
+	import.meta.url.includes("$bunfs") ||
+	import.meta.url.includes("~BUN") ||
+	import.meta.url.includes("%7EBUN");
+
+// Dev-mode assets: packages/coding-agent/src/browser → packages/office-pane/dist.
+const DEV_DIST_DIR = path.resolve(import.meta.dir, "..", "..", "..", "office-pane", "dist");
+const COMPILED_DIR_ROOT = path.join(os.tmpdir(), "xcsh-office-pane");
+
+const getEmbeddedArchive = (() => {
+	const txt = embeddedPaneArchiveTxt.replaceAll(/[\s\r\n]/g, "").trim();
+	if (!txt) return null;
+	return () => Buffer.from(txt, "base64");
+})();
+
+let compiledDirPromise: Promise<string> | null = null;
+
+/**
+ * Sanitize an archive-relative path, rejecting anything that would escape the
+ * extraction/serve root (`..`, absolute paths, empty/`.`). Returns the
+ * normalized forward-slash path, or `null` when the input is unsafe.
+ */
+export function sanitizeArchivePath(archivePath: string): string | null {
+	const normalized = archivePath.replaceAll("\\", "/").replace(/^\.\//, "");
+	if (!normalized || normalized === ".") return null;
+	if (normalized.includes("..") || path.isAbsolute(normalized)) return null;
+	return normalized;
+}
+
+async function extractEmbeddedArchive(archiveBytes: Buffer, outputDir: string): Promise<void> {
+	const archive = new Bun.Archive(archiveBytes);
+	const files = await archive.files();
+	const extractRoot = path.resolve(outputDir);
+
+	for (const [archivePath, file] of files) {
+		const sanitizedPath = sanitizeArchivePath(archivePath);
+		if (!sanitizedPath) continue;
+		const destinationPath = path.resolve(extractRoot, sanitizedPath);
+		if (!destinationPath.startsWith(extractRoot + path.sep)) {
+			throw new Error(`Archive entry escapes extraction directory: ${archivePath}`);
+		}
+		await Bun.write(destinationPath, file);
+	}
+}
+
+/**
+ * Resolve the directory the assets are served from: the extracted embedded
+ * bundle in a compiled binary, else `packages/office-pane/dist` in dev.
+ */
+export async function getOfficePaneDir(): Promise<string> {
+	if (!IS_BUN_COMPILED) return DEV_DIST_DIR;
+	if (compiledDirPromise) return compiledDirPromise;
+
+	const archiveBytes = getEmbeddedArchive?.();
+	if (!archiveBytes) {
+		throw new Error("Compiled office-pane bundle missing. Rebuild the binary with the embedded office-pane assets.");
+	}
+
+	compiledDirPromise = (async () => {
+		const bundleHash = Bun.hash(archiveBytes).toString(16);
+		const outputDir = path.join(COMPILED_DIR_ROOT, bundleHash);
+		const markerPath = path.join(outputDir, "taskpane.html");
+		try {
+			if ((await fs.stat(markerPath)).isFile()) return outputDir;
+		} catch {}
+
+		await fs.rm(outputDir, { recursive: true, force: true });
+		await fs.mkdir(outputDir, { recursive: true });
+		await extractEmbeddedArchive(archiveBytes, outputDir);
+		return outputDir;
+	})();
+
+	return compiledDirPromise;
+}
+
+/**
+ * Pure request handler: map a URL pathname to a file under `dir` and return it
+ * with the content-type inferred from its extension, or a 404. `/` maps to
+ * `taskpane.html`. Path-traversal is rejected before any filesystem access.
+ */
+export async function handleAssetRequest(pathname: string, dir: string): Promise<Response> {
+	const requested = pathname === "/" ? "taskpane.html" : pathname.replace(/^\/+/, "");
+	const safe = sanitizeArchivePath(requested);
+	if (!safe) return new Response("Not Found", { status: 404 });
+
+	const root = path.resolve(dir);
+	const fullPath = path.resolve(root, safe);
+	if (fullPath !== root && !fullPath.startsWith(root + path.sep)) {
+		return new Response("Not Found", { status: 404 });
+	}
+
+	const file = Bun.file(fullPath);
+	if (await file.exists()) return new Response(file);
+	return new Response("Not Found", { status: 404 });
+}
+
+/** Read the embedded/dev manifest.json as text (for `xcsh office manifest`). */
+export async function readManifest(): Promise<string> {
+	const dir = await getOfficePaneDir();
+	return Bun.file(path.join(dir, "manifest.json")).text();
+}
+
+export interface OfficePaneServer {
+	port: number;
+	url: string;
+	taskpaneUrl: string;
+	/** true when a publicly-trusted `*.local-ip.sh` cert is in use. */
+	trusted: boolean;
+	stop: () => void;
+}
+
+/**
+ * Start the fixed :8444 HTTPS listener serving the embedded/dev assets. Resolves
+ * TLS via {@link resolveBridgeTls} (the shared local-ip.sh cert). Serves only GET
+ * (405 otherwise); unknown paths return 404.
+ */
+export async function startOfficePaneServer(port = OFFICE_PANE_PORT): Promise<OfficePaneServer> {
+	const dir = await getOfficePaneDir();
+	const tls = await resolveBridgeTls();
+
+	const server = Bun.serve({
+		port,
+		hostname: OFFICE_PANE_HOSTNAME,
+		tls,
+		async fetch(req) {
+			if (req.method !== "GET" && req.method !== "HEAD") {
+				return new Response("Method Not Allowed", { status: 405 });
+			}
+			try {
+				const url = new URL(req.url);
+				return await handleAssetRequest(url.pathname, dir);
+			} catch (error) {
+				return new Response(error instanceof Error ? error.message : "Internal Server Error", { status: 500 });
+			}
+		},
+	});
+
+	return {
+		port: server.port ?? port,
+		url: OFFICE_PANE_URL,
+		taskpaneUrl: OFFICE_PANE_TASKPANE_URL,
+		trusted: tls !== undefined,
+		stop: () => server.stop(),
+	};
+}

package/src/cli/office-cli.ts

@@ -0,0 +1,107 @@
+/**
+ * `xcsh office` command handlers.
+ *
+ * Drives the embedded Office task pane: start its fixed :8444 HTTPS listener
+ * (`serve`), emit the unified manifest (`manifest`), or sideload it into a
+ * desktop Office app (`sideload`). The serving/embed logic lives in
+ * `../browser/office-pane-server`; this module is the thin, testable CLI seam
+ * mirroring `stats-cli.ts` / `chrome-cli.ts`.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { readManifest, startOfficePaneServer } from "../browser/office-pane-server";
+
+/** The subcommands `xcsh office` accepts (also the Args `options` constraint). */
+export const OFFICE_ACTIONS = ["serve", "manifest", "sideload"] as const;
+export type OfficeAction = (typeof OFFICE_ACTIONS)[number];
+
+/** Desktop Office apps a sideload can target. */
+export const OFFICE_APPS = ["excel", "powerpoint", "word"] as const;
+export type OfficeApp = (typeof OFFICE_APPS)[number];
+
+export interface OfficeCommandArgs {
+	action: OfficeAction;
+	/** Target app for `sideload` (defaults to excel). */
+	app?: OfficeApp;
+	/** Optional output path for `manifest`; when omitted, print to stdout. */
+	out?: string;
+}
+
+/**
+ * Resolve the manifest text and optionally write it to `outPath`. Returns the
+ * manifest JSON string. Exposed for unit testing.
+ */
+export async function writeManifest(outPath?: string): Promise<string> {
+	const text = await readManifest();
+	if (outPath) {
+		await Bun.write(outPath, text);
+	}
+	return text;
+}
+
+/** Start the :8444 listener, print the task-pane URL, and block until killed. */
+async function runServe(): Promise<void> {
+	const server = await startOfficePaneServer();
+	console.log(`Serving the xcsh Office task pane at ${server.taskpaneUrl}`);
+	if (!server.trusted) {
+		console.warn(
+			"Warning: a publicly-trusted local-ip.sh cert could not be provisioned; using a self-signed fallback. " +
+				"Office's WebView may refuse to load the page until the cert is trusted.",
+		);
+	}
+	console.log("Press Ctrl+C to stop.");
+	// Bun.serve holds the event loop open; block run() so the process stays alive.
+	await new Promise<never>(() => {});
+}
+
+/** Emit the manifest to a temp file and run the Office sideload (best-effort). */
+async function runSideload(app: OfficeApp): Promise<void> {
+	const text = await readManifest();
+	const dir = await fs.mkdtemp(path.join(os.tmpdir(), "xcsh-office-sideload-"));
+	const manifestPath = path.join(dir, "manifest.json");
+	await Bun.write(manifestPath, text);
+	console.log(`Wrote manifest to ${manifestPath}`);
+	console.log(`Sideloading into ${app} (requires the office-addin-debugging / atk tool on PATH)...`);
+
+	const result = spawnSync("office-addin-debugging", ["start", manifestPath, "desktop", "--app", app], {
+		stdio: "inherit",
+	});
+	if (result.error) {
+		const code = (result.error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") {
+			console.error(
+				"office-addin-debugging was not found on PATH. Install it (e.g. `npm i -g office-addin-debugging` " +
+					"or `npm i -g @microsoft/m365agentstoolkit-cli` for `atk`), then run:\n" +
+					`  office-addin-debugging start ${manifestPath} desktop --app ${app}`,
+			);
+			return;
+		}
+		throw result.error;
+	}
+	if (typeof result.status === "number" && result.status !== 0) {
+		console.error(`office-addin-debugging exited with status ${result.status}.`);
+	}
+}
+
+/** Dispatch an `xcsh office <action>` invocation. */
+export async function runOfficeCommand(args: OfficeCommandArgs): Promise<void> {
+	switch (args.action) {
+		case "serve":
+			await runServe();
+			return;
+		case "manifest": {
+			const text = await writeManifest(args.out);
+			if (args.out) {
+				console.log(`Wrote manifest to ${args.out}`);
+			} else {
+				console.log(text);
+			}
+			return;
+		}
+		case "sideload":
+			await runSideload(args.app ?? "excel");
+			return;
+	}
+}

package/src/cli.ts

@@ -58,6 +58,7 @@ const commands: CommandEntry[] = [
 	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
 	{ name: "jupyter", load: () => import("./commands/jupyter").then(m => m.default) },
 	{ name: "manager", load: () => import("./commands/manager").then(m => m.default) },
+	{ name: "office", load: () => import("./commands/office").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
 	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
 	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },

package/src/commands/office.ts

@@ -0,0 +1,42 @@
+/**
+ * Serve, print, or sideload the embedded xcsh Office task pane.
+ */
+import { Args, Command, Flags } from "@f5-sales-demo/pi-utils/cli";
+import { OFFICE_ACTIONS, OFFICE_APPS, type OfficeAction, type OfficeApp, runOfficeCommand } from "../cli/office-cli";
+
+export default class Office extends Command {
+	static description = "Serve, print, or sideload the embedded xcsh Office task pane";
+
+	static args = {
+		action: Args.string({
+			description: "serve | manifest | sideload",
+			required: false,
+			options: OFFICE_ACTIONS,
+		}),
+		app: Args.string({
+			description: "Office app for sideload (excel | powerpoint | word)",
+			required: false,
+			options: OFFICE_APPS,
+		}),
+	};
+
+	static flags = {
+		out: Flags.string({ char: "o", description: "Write manifest.json to this path (manifest action)" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Office);
+		if (!args.action) {
+			console.log(`Usage: xcsh office <${OFFICE_ACTIONS.join("|")}>`);
+			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");
+			return;
+		}
+		await runOfficeCommand({
+			action: args.action as OfficeAction,
+			app: args.app as OfficeApp | undefined,
+			out: flags.out,
+		});
+	}
+}

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.65.0",
-	"commit": "342e21815d71783c1c2b1ffe233bc0078fbcc44a",
-	"shortCommit": "342e218",
+	"version": "19.66.1",
+	"commit": "818d8885828e0e5fb5a9c23d5317d2584ed1a33e",
+	"shortCommit": "818d888",
 	"branch": "main",
-	"tag": "v19.65.0",
-	"commitDate": "2026-07-20T18:44:32Z",
-	"buildDate": "2026-07-20T19:07:31.313Z",
+	"tag": "v19.66.1",
+	"commitDate": "2026-07-20T22:06:59Z",
+	"buildDate": "2026-07-20T22:36:00.677Z",
 	"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/342e21815d71783c1c2b1ffe233bc0078fbcc44a",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.65.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/818d8885828e0e5fb5a9c23d5317d2584ed1a33e",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.66.1"
 };