@f5xc-salesdemos/xcsh 2.2.0 → 14.0.2

package/scripts/generate-docs-index.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env bun
+
+import * as path from "node:path";
+import { Glob } from "bun";
+
+const docsDir = path.resolve(import.meta.dir, "../../../docs");
+const outputPath = path.resolve(import.meta.dir, "../src/internal-urls/docs-index.generated.ts");
+
+const glob = new Glob("**/*.md");
+const entries: string[] = [];
+for await (const relativePath of glob.scan(docsDir)) {
+	entries.push(relativePath.split(path.sep).join("/"));
+}
+entries.sort();
+
+const docsWithContent = await Promise.all(
+	entries.map(async relativePath => ({
+		relativePath,
+		content: await Bun.file(path.join(docsDir, relativePath)).text(),
+	})),
+);
+
+const filenamesLiteral = JSON.stringify(entries);
+
+const mapEntries = docsWithContent
+	.map(({ relativePath, content }) => `\t${JSON.stringify(relativePath)}: ${JSON.stringify(content)},`)
+	.join("\n");
+const output = [
+	"// Auto-generated by scripts/generate-docs-index.ts - DO NOT EDIT",
+	"",
+	`export const EMBEDDED_DOC_FILENAMES: readonly string[] = ${filenamesLiteral};`,
+	"",
+	`export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {`,
+	`${mapEntries}`,
+	`};`,
+	"",
+].join("\n");
+
+await Bun.write(outputPath, output);
+console.log(`Generated ${path.relative(process.cwd(), outputPath)} (${entries.length} docs)`);

package/scripts/generate-template.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env bun
+/**
+ * Pre-compute the HTML template at publish time.
+ * This avoids the Bun macro restriction in node_modules.
+ */
+
+const dir = new URL("../src/export/html/", import.meta.url).pathname;
+
+// Read all files
+const html = await Bun.file(`${dir}template.html`).text();
+const css = await Bun.file(`${dir}template.css`).text();
+const js = await Bun.file(`${dir}template.js`).text();
+
+// Minify CSS
+const minifiedCss = css
+	.replace(/\/\*[\s\S]*?\*\//g, "")
+	.replace(/\s+/g, " ")
+	.replace(/\s*([{}:;,])\s*/g, "$1")
+	.trim();
+
+// Inline everything
+const template = html
+	.replace("<template-css/>", `<style>${minifiedCss}</style>`)
+	.replace("<template-js/>", `<script>${js}</script>`);
+
+// Write generated file
+const output = `// Auto-generated by scripts/generate-template.ts - DO NOT EDIT
+export const TEMPLATE = ${JSON.stringify(template)};
+`;
+
+await Bun.write(`${dir}template.generated.ts`, output);
+console.log("Generated template.generated.ts");

package/src/async/index.ts

@@ -0,0 +1 @@
+export * from "./job-manager";

package/src/async/job-manager.ts

@@ -0,0 +1,383 @@
+import { logger, Snowflake } from "@f5xc-salesdemos/pi-utils";
+
+const DELIVERY_RETRY_BASE_MS = 500;
+const DELIVERY_RETRY_MAX_MS = 30_000;
+const DELIVERY_RETRY_JITTER_MS = 200;
+const DEFAULT_RETENTION_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_RUNNING_JOBS = 15;
+
+export interface AsyncJob {
+	id: string;
+	type: "bash" | "task";
+	status: "running" | "completed" | "failed" | "cancelled";
+	startTime: number;
+	label: string;
+	abortController: AbortController;
+	promise: Promise<void>;
+	resultText?: string;
+	errorText?: string;
+}
+
+export interface AsyncJobManagerOptions {
+	onJobComplete: (jobId: string, text: string, job?: AsyncJob) => void | Promise<void>;
+	maxRunningJobs?: number;
+	retentionMs?: number;
+}
+
+interface AsyncJobDelivery {
+	jobId: string;
+	text: string;
+	attempt: number;
+	nextAttemptAt: number;
+	lastError?: string;
+}
+
+export interface AsyncJobDeliveryState {
+	queued: number;
+	delivering: boolean;
+	nextRetryAt?: number;
+	pendingJobIds: string[];
+}
+
+export interface AsyncJobRegisterOptions {
+	id?: string;
+	onProgress?: (text: string, details?: Record<string, unknown>) => void | Promise<void>;
+}
+
+export class AsyncJobManager {
+	readonly #jobs = new Map<string, AsyncJob>();
+	readonly #deliveries: AsyncJobDelivery[] = [];
+	readonly #suppressedDeliveries = new Set<string>();
+	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
+	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
+	readonly #maxRunningJobs: number;
+	readonly #retentionMs: number;
+	#deliveryLoop: Promise<void> | undefined;
+	#disposed = false;
+
+	constructor(options: AsyncJobManagerOptions) {
+		this.#onJobComplete = options.onJobComplete;
+		this.#maxRunningJobs = Math.max(1, Math.floor(options.maxRunningJobs ?? DEFAULT_MAX_RUNNING_JOBS));
+		this.#retentionMs = Math.max(0, Math.floor(options.retentionMs ?? DEFAULT_RETENTION_MS));
+	}
+
+	register(
+		type: "bash" | "task",
+		label: string,
+		run: (ctx: {
+			jobId: string;
+			signal: AbortSignal;
+			reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
+		}) => Promise<string>,
+		options?: AsyncJobRegisterOptions,
+	): string {
+		if (this.#disposed) {
+			throw new Error("Async job manager is disposed");
+		}
+		const runningCount = this.getRunningJobs().length;
+		if (runningCount >= this.#maxRunningJobs) {
+			throw new Error(
+				`Background job limit reached (${this.#maxRunningJobs}). Wait for running jobs to finish or cancel one.`,
+			);
+		}
+
+		const id = this.#resolveJobId(options?.id);
+		this.#suppressedDeliveries.delete(id);
+		const abortController = new AbortController();
+		const startTime = Date.now();
+
+		const job: AsyncJob = {
+			id,
+			type,
+			status: "running",
+			startTime,
+			label,
+			abortController,
+			promise: Promise.resolve(),
+		};
+
+		const reportProgress = async (text: string, details?: Record<string, unknown>): Promise<void> => {
+			if (!options?.onProgress) return;
+			try {
+				await options.onProgress(text, details);
+			} catch (error) {
+				logger.warn("Async job progress callback failed", {
+					jobId: id,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		};
+		job.promise = (async () => {
+			try {
+				const text = await run({ jobId: id, signal: abortController.signal, reportProgress });
+				if (job.status === "cancelled") {
+					job.resultText = text;
+					this.#scheduleEviction(id);
+					return;
+				}
+				job.status = "completed";
+				job.resultText = text;
+				this.#enqueueDelivery(id, text);
+				this.#scheduleEviction(id);
+			} catch (error) {
+				if (job.status === "cancelled") {
+					job.errorText = error instanceof Error ? error.message : String(error);
+					this.#scheduleEviction(id);
+					return;
+				}
+				const errorText = error instanceof Error ? error.message : String(error);
+				job.status = "failed";
+				job.errorText = errorText;
+				this.#enqueueDelivery(id, errorText);
+				this.#scheduleEviction(id);
+			}
+		})();
+
+		this.#jobs.set(id, job);
+		return id;
+	}
+
+	cancel(id: string): boolean {
+		const job = this.#jobs.get(id);
+		if (!job) return false;
+		if (job.status !== "running") return false;
+		job.status = "cancelled";
+		job.abortController.abort();
+		this.#scheduleEviction(id);
+		return true;
+	}
+
+	getJob(id: string): AsyncJob | undefined {
+		return this.#jobs.get(id);
+	}
+
+	getRunningJobs(): AsyncJob[] {
+		return Array.from(this.#jobs.values()).filter(job => job.status === "running");
+	}
+
+	getRecentJobs(limit = 10): AsyncJob[] {
+		return Array.from(this.#jobs.values())
+			.filter(job => job.status !== "running")
+			.sort((a, b) => b.startTime - a.startTime)
+			.slice(0, limit);
+	}
+
+	getAllJobs(): AsyncJob[] {
+		return Array.from(this.#jobs.values());
+	}
+
+	getDeliveryState(): AsyncJobDeliveryState {
+		const nextRetryAt = this.#deliveries.reduce<number | undefined>((next, delivery) => {
+			if (next === undefined) return delivery.nextAttemptAt;
+			return Math.min(next, delivery.nextAttemptAt);
+		}, undefined);
+
+		return {
+			queued: this.#deliveries.length,
+			delivering: this.#deliveryLoop !== undefined,
+			nextRetryAt,
+			pendingJobIds: this.#deliveries.map(delivery => delivery.jobId),
+		};
+	}
+
+	hasPendingDeliveries(): boolean {
+		return this.#deliveries.length > 0;
+	}
+
+	acknowledgeDeliveries(jobIds: string[]): number {
+		const uniqueJobIds = Array.from(new Set(jobIds.map(id => id.trim()).filter(id => id.length > 0)));
+		if (uniqueJobIds.length === 0) return 0;
+
+		for (const jobId of uniqueJobIds) {
+			this.#suppressedDeliveries.add(jobId);
+		}
+
+		const before = this.#deliveries.length;
+		this.#deliveries.splice(
+			0,
+			this.#deliveries.length,
+			...this.#deliveries.filter(delivery => !this.#suppressedDeliveries.has(delivery.jobId)),
+		);
+		return before - this.#deliveries.length;
+	}
+
+	cancelAll(): void {
+		for (const job of this.getRunningJobs()) {
+			job.status = "cancelled";
+			job.abortController.abort();
+			this.#scheduleEviction(job.id);
+		}
+	}
+
+	async waitForAll(): Promise<void> {
+		await Promise.all(Array.from(this.#jobs.values()).map(job => job.promise));
+	}
+
+	async drainDeliveries(options?: { timeoutMs?: number }): Promise<boolean> {
+		const timeoutMs = options?.timeoutMs;
+		const hasDeadline = timeoutMs !== undefined;
+		const deadline = hasDeadline ? Date.now() + Math.max(timeoutMs, 0) : Number.POSITIVE_INFINITY;
+
+		while (this.hasPendingDeliveries()) {
+			this.#ensureDeliveryLoop();
+			const loop = this.#deliveryLoop;
+			if (!loop) {
+				continue;
+			}
+
+			if (!hasDeadline) {
+				await loop;
+				continue;
+			}
+
+			const remainingMs = deadline - Date.now();
+			if (remainingMs <= 0) {
+				return false;
+			}
+
+			await Promise.race([loop, Bun.sleep(remainingMs)]);
+			if (Date.now() >= deadline && this.hasPendingDeliveries()) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	async dispose(options?: { timeoutMs?: number }): Promise<boolean> {
+		this.#disposed = true;
+		this.#clearEvictionTimers();
+		this.cancelAll();
+		await this.waitForAll();
+		const drained = await this.drainDeliveries({ timeoutMs: options?.timeoutMs ?? 3_000 });
+		this.#clearEvictionTimers();
+		this.#jobs.clear();
+		this.#deliveries.length = 0;
+		this.#suppressedDeliveries.clear();
+		return drained;
+	}
+
+	#resolveJobId(preferredId?: string): string {
+		if (!preferredId || preferredId.trim().length === 0) {
+			return `bg_${Snowflake.next()}`;
+		}
+
+		const base = preferredId.trim();
+		if (!this.#jobs.has(base)) return base;
+
+		let suffix = 2;
+		let candidate = `${base}-${suffix}`;
+		while (this.#jobs.has(candidate)) {
+			suffix += 1;
+			candidate = `${base}-${suffix}`;
+		}
+		return candidate;
+	}
+
+	#scheduleEviction(jobId: string): void {
+		if (this.#retentionMs <= 0) {
+			this.#jobs.delete(jobId);
+			this.#suppressedDeliveries.delete(jobId);
+			return;
+		}
+		const existing = this.#evictionTimers.get(jobId);
+		if (existing) {
+			clearTimeout(existing);
+		}
+		const timer = setTimeout(() => {
+			this.#evictionTimers.delete(jobId);
+			this.#jobs.delete(jobId);
+			this.#suppressedDeliveries.delete(jobId);
+		}, this.#retentionMs);
+		timer.unref();
+		this.#evictionTimers.set(jobId, timer);
+	}
+
+	#clearEvictionTimers(): void {
+		for (const timer of this.#evictionTimers.values()) {
+			clearTimeout(timer);
+		}
+		this.#evictionTimers.clear();
+	}
+
+	#isDeliverySuppressed(jobId: string): boolean {
+		return this.#suppressedDeliveries.has(jobId);
+	}
+
+	#enqueueDelivery(jobId: string, text: string): void {
+		if (this.#isDeliverySuppressed(jobId)) {
+			return;
+		}
+		this.#deliveries.push({
+			jobId,
+			text,
+			attempt: 0,
+			nextAttemptAt: Date.now(),
+		});
+		this.#ensureDeliveryLoop();
+	}
+
+	#ensureDeliveryLoop(): void {
+		if (this.#deliveryLoop) {
+			return;
+		}
+
+		this.#deliveryLoop = this.#runDeliveryLoop()
+			.catch(error => {
+				logger.error("Async job delivery loop crashed", { error: String(error) });
+			})
+			.finally(() => {
+				this.#deliveryLoop = undefined;
+				if (this.#deliveries.length > 0) {
+					this.#ensureDeliveryLoop();
+				}
+			});
+	}
+
+	async #runDeliveryLoop(): Promise<void> {
+		while (this.#deliveries.length > 0) {
+			const delivery = this.#deliveries[0];
+			if (this.#isDeliverySuppressed(delivery.jobId)) {
+				this.#deliveries.shift();
+				continue;
+			}
+			const waitMs = delivery.nextAttemptAt - Date.now();
+			if (waitMs > 0) {
+				await Bun.sleep(waitMs);
+			}
+			if (this.#deliveries[0] !== delivery) {
+				continue;
+			}
+			if (this.#isDeliverySuppressed(delivery.jobId)) {
+				this.#deliveries.shift();
+				continue;
+			}
+
+			try {
+				await this.#onJobComplete(delivery.jobId, delivery.text, this.#jobs.get(delivery.jobId));
+				this.#deliveries.shift();
+			} catch (error) {
+				delivery.attempt += 1;
+				delivery.lastError = error instanceof Error ? error.message : String(error);
+				delivery.nextAttemptAt = Date.now() + this.#getRetryDelay(delivery.attempt);
+				this.#deliveries.shift();
+				if (!this.#isDeliverySuppressed(delivery.jobId)) {
+					this.#deliveries.push(delivery);
+				}
+				logger.warn("Async job completion delivery failed", {
+					jobId: delivery.jobId,
+					attempt: delivery.attempt,
+					nextRetryAt: delivery.nextAttemptAt,
+					error: delivery.lastError,
+				});
+			}
+		}
+	}
+
+	#getRetryDelay(attempt: number): number {
+		const exp = Math.min(Math.max(attempt - 1, 0), 8);
+		const backoffMs = DELIVERY_RETRY_BASE_MS * 2 ** exp;
+		const jitterMs = Math.floor(Math.random() * DELIVERY_RETRY_JITTER_MS);
+		return Math.min(DELIVERY_RETRY_MAX_MS, backoffMs + jitterMs);
+	}
+}

package/src/autoresearch/apply-contract-to-state.ts

@@ -0,0 +1,24 @@
+import { inferMetricUnitFromName } from "./helpers";
+import type { AutoresearchContract, ExperimentState } from "./types";
+
+/**
+ * Updates session fields from a validated `autoresearch.md` parse (same fields as `init_experiment`).
+ * Does not touch `name`, `currentSegment`, `results`, `bestMetric`, `confidence`, or `maxExperiments`.
+ */
+export function applyAutoresearchContractToExperimentState(
+	contract: AutoresearchContract,
+	state: ExperimentState,
+): void {
+	const benchmarkContract = contract.benchmark;
+	state.metricName = benchmarkContract.primaryMetric ?? state.metricName;
+	state.metricUnit = benchmarkContract.metricUnit;
+	state.bestDirection = benchmarkContract.direction ?? "lower";
+	state.secondaryMetrics = benchmarkContract.secondaryMetrics.map(name => ({
+		name,
+		unit: inferMetricUnitFromName(name),
+	}));
+	state.benchmarkCommand = benchmarkContract.command?.trim() ?? state.benchmarkCommand;
+	state.scopePaths = [...contract.scopePaths];
+	state.offLimits = [...contract.offLimits];
+	state.constraints = [...contract.constraints];
+}

package/src/autoresearch/command-resume.md

@@ -0,0 +1,17 @@
+Resume autoresearch from the attached notes.
+
+@{{autoresearch_md_path}}
+
+{{branch_status_line}}
+{{#if has_resume_context}}
+
+Additional context from the user:
+
+{{resume_context}}
+{{/if}}
+
+Use the notes as the source of truth for the current direction, scope, and constraints.
+- inspect recent git history for context
+- inspect `autoresearch.jsonl` if it exists
+- continue the most promising unfinished direction on the current protected branch
+- keep iterating until interrupted or until the configured iteration cap is reached