oh-my-opencode 4.9.1 → 4.10.0

package/packages/omo-codex/plugin/components/bootstrap/src/cli.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { downloadFromManifest } from "./download.ts";
+import { runSessionStartHook } from "./hook.ts";
+import { runBootstrapWorker } from "./worker.ts";
+
+export {
+	bootstrapLocks,
+	detectInstallFlow,
+	detectInstallFlowDetailed,
+	detectInstallFlowForTest,
+	detectInstallFlowFromEnvironment,
+	INSTALL_SNAPSHOT_FILENAME,
+	resolveBootstrapLockPath,
+	resolveBootstrapStatePath,
+	resolveCodexHome,
+} from "./environment.ts";
+export type {
+	BootstrapLockHandle,
+	BootstrapLocksOptions,
+	CodexHomeResolution,
+	CodexHomeSource,
+	ConfigSourceSignal,
+	DetectInstallFlowFromEnvironmentOptions,
+	DetectInstallFlowOptions,
+	InstallFlow,
+	InstallFlowDetection,
+	ResolveCodexHomeOptions,
+} from "./environment.ts";
+export { BOOTSTRAP_RESTART_NOTICE, executeSessionStartHook, runSessionStartHook } from "./hook.ts";
+export {
+	runSgProvision,
+	SG_FORCE_PROVISION_ENV_KEY,
+	SG_PROVISION_COMPONENT,
+	sgProvisionDestination,
+} from "./provision.ts";
+export type { ResolvePreexistingSgOptions, SgProvisionSeams } from "./provision.ts";
+export { GIT_BASH_INSTALL_HINT, runWorkerSetup, SETUP_MARKETPLACE_NAME, SETUP_PLUGIN_NAME } from "./setup.ts";
+export type { SetupRunCommand, WorkerSetupOptions } from "./setup.ts";
+export type {
+	SessionStartAction,
+	SessionStartHookOptions,
+	SessionStartHookResult,
+	WorkerSpawnInvocation,
+} from "./hook.ts";
+export {
+	appendBootstrapLog,
+	BOOTSTRAP_DOCTOR_HINT,
+	defaultWorkerSteps,
+	parseBootstrapState,
+	parseWorkerFlags,
+	readBootstrapState,
+	readPluginVersion,
+	resolvePluginDataRoot,
+	runBootstrapWorker,
+} from "./worker.ts";
+export type {
+	DefaultWorkerStepsSeams,
+	BootstrapDegradedEntry,
+	BootstrapRunStatus,
+	BootstrapState,
+	BootstrapStepOutcome,
+	BootstrapWorkerContext,
+	BootstrapWorkerFlags,
+	BootstrapWorkerResult,
+	BootstrapWorkerSkipReason,
+	BootstrapWorkerStep,
+	RunBootstrapWorkerOptions,
+} from "./worker.ts";
+
+const TOP_LEVEL_HELP =
+	"Usage:\n  omo-bootstrap hook session-start\n  omo-bootstrap worker [--codex-home <dir>] [--once] [--only <step>] [--manifest-dir <dir>]\n  omo-bootstrap download <manifest> <platform> <destination-dir>\n  omo-bootstrap help | --help | -h\n";
+
+async function runDownloadCommand(args: readonly string[]): Promise<number> {
+	const [manifestName, platformKey, destinationDir] = args;
+	if (manifestName === undefined || platformKey === undefined || destinationDir === undefined) {
+		process.stderr.write(`[omo-bootstrap] download requires <manifest> <platform> <destination-dir>\n${TOP_LEVEL_HELP}`);
+		return 1;
+	}
+	try {
+		const destination = await downloadFromManifest({ destinationDir, manifestName, platformKey });
+		process.stdout.write(`OK:${destination}\n`);
+		return 0;
+	} catch (error) {
+		process.stderr.write(`[omo-bootstrap] download failed: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+}
+
+async function runWorkerCommand(args: readonly string[]): Promise<number> {
+	let result;
+	try {
+		result = await runBootstrapWorker({ argv: args, env: process.env });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (/flag/.test(message)) {
+			process.stderr.write(`[omo-bootstrap] ${message}\n${TOP_LEVEL_HELP}`);
+			return 1;
+		}
+		// Runtime worker failures must never surface as non-zero exits; the
+		// degraded ledger in state.json is the error channel.
+		process.stderr.write(`[omo-bootstrap] worker error: ${message}\n`);
+		return 0;
+	}
+	process.stdout.write(
+		result.ran ? `[omo-bootstrap] worker finished: ${result.status}\n` : `[omo-bootstrap] worker skipped: ${result.reason}\n`,
+	);
+	return 0;
+}
+
+async function main(): Promise<number> {
+	const argv = process.argv.slice(2);
+	const command = argv[0];
+	if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+		process.stdout.write(TOP_LEVEL_HELP);
+		return 0;
+	}
+	if (command === "hook" && argv[1] === "session-start") {
+		return runSessionStartHook({ env: process.env, stdin: process.stdin });
+	}
+	if (command === "worker") {
+		return runWorkerCommand(argv.slice(1));
+	}
+	if (command === "download") {
+		return runDownloadCommand(argv.slice(1));
+	}
+	process.stderr.write(`[omo-bootstrap] unknown command: ${argv.join(" ")}\n${TOP_LEVEL_HELP}`);
+	return 1;
+}
+
+function isProcessEntry(): boolean {
+	const entry = process.argv[1];
+	if (entry === undefined) return false;
+	try {
+		return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+	} catch {
+		return false;
+	}
+}
+
+if (isProcessEntry()) {
+	main()
+		.then((code) => {
+			process.exit(code);
+		})
+		.catch((error: unknown) => {
+			// The SessionStart hook path must never fail the session: log and exit 0.
+			process.stderr.write(`[omo-bootstrap] ${error instanceof Error ? error.message : String(error)}\n`);
+			process.exit(0);
+		});
+}

package/packages/omo-codex/plugin/components/bootstrap/src/download.ts

@@ -0,0 +1,212 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir, readFile, rename, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import type { ReadableStream as NodeWebReadableStream } from "node:stream/web";
+import { fileURLToPath } from "node:url";
+
+export type DownloadErrorCode = "checksum-mismatch" | "download-failed" | "unsupported-platform";
+
+export class DownloadError extends Error {
+	readonly code: DownloadErrorCode;
+
+	constructor(code: DownloadErrorCode, message: string) {
+		super(message);
+		this.name = "DownloadError";
+		this.code = code;
+	}
+}
+
+export class ChecksumMismatchError extends DownloadError {
+	readonly expectedSha256: string;
+	readonly actualSha256: string;
+
+	constructor(options: { readonly url: string; readonly expectedSha256: string; readonly actualSha256: string }) {
+		super(
+			"checksum-mismatch",
+			`Checksum mismatch for ${options.url}: expected sha256 ${options.expectedSha256} but downloaded sha256 ${options.actualSha256}; deleted the partial download.`,
+		);
+		this.name = "ChecksumMismatchError";
+		this.expectedSha256 = options.expectedSha256;
+		this.actualSha256 = options.actualSha256;
+	}
+}
+
+export class UnsupportedPlatformError extends DownloadError {
+	readonly manifestName: string;
+	readonly platformKey: string;
+
+	constructor(options: {
+		readonly manifestName: string;
+		readonly platformKey: string;
+		readonly availablePlatforms: readonly string[];
+	}) {
+		super(
+			"unsupported-platform",
+			`Manifest "${options.manifestName}" has no asset for unsupported platform "${options.platformKey}" (available: ${options.availablePlatforms.join(", ")}).`,
+		);
+		this.name = "UnsupportedPlatformError";
+		this.manifestName = options.manifestName;
+		this.platformKey = options.platformKey;
+	}
+}
+
+export type FetchLike = (url: string) => Promise<Response>;
+
+export interface ManifestAsset {
+	readonly url: string;
+	readonly sha256: string;
+}
+
+export interface AssetManifest {
+	readonly name: string;
+	readonly version: string;
+	readonly platforms: Readonly<Record<string, ManifestAsset>>;
+}
+
+export interface DownloadChecksummedAssetOptions {
+	readonly url: string;
+	readonly sha256: string;
+	readonly destination: string;
+	readonly fetchImpl?: FetchLike;
+	readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface DownloadFromManifestOptions {
+	readonly manifestName: string;
+	readonly platformKey: string;
+	readonly destinationDir: string;
+	readonly fetchImpl?: FetchLike;
+	readonly env?: NodeJS.ProcessEnv;
+	readonly manifestsDir?: string;
+}
+
+const PROXY_ENV_KEYS = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"] as const;
+
+function proxyLimitationNote(env: NodeJS.ProcessEnv): string {
+	const configuredKey = PROXY_ENV_KEYS.find((key) => (env[key] ?? "").trim().length > 0);
+	if (configuredKey === undefined) return "";
+	return ` Note: ${configuredKey} is set, but the bootstrap downloader does not tunnel through HTTP(S) proxies in v1; the download was attempted directly.`;
+}
+
+function describeFailure(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+async function writeBodyToFile(body: NodeWebReadableStream<Uint8Array> | null, tempPath: string): Promise<string> {
+	const hash = createHash("sha256");
+	if (body === null) {
+		await pipeline(Readable.from([]), createWriteStream(tempPath));
+		return hash.digest("hex");
+	}
+	await pipeline(
+		Readable.fromWeb(body),
+		async function* hashChunks(source: AsyncIterable<Uint8Array>): AsyncGenerator<Buffer> {
+			for await (const chunk of source) {
+				const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+				hash.update(buffer);
+				yield buffer;
+			}
+		},
+		createWriteStream(tempPath),
+	);
+	return hash.digest("hex");
+}
+
+export async function downloadChecksummedAsset(options: DownloadChecksummedAssetOptions): Promise<string> {
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+	const env = options.env ?? process.env;
+	const expectedSha256 = options.sha256.toLowerCase();
+	await mkdir(dirname(options.destination), { recursive: true });
+	const tempPath = `${options.destination}.${randomUUID().slice(0, 8)}.partial`;
+
+	let response: Response;
+	try {
+		response = await fetchImpl(options.url);
+	} catch (error) {
+		throw new DownloadError(
+			"download-failed",
+			`Download failed for ${options.url}: ${describeFailure(error)}.${proxyLimitationNote(env)}`,
+		);
+	}
+	if (!response.ok) {
+		throw new DownloadError(
+			"download-failed",
+			`Download failed for ${options.url}: HTTP ${response.status}.${proxyLimitationNote(env)}`,
+		);
+	}
+
+	let actualSha256: string;
+	try {
+		actualSha256 = await writeBodyToFile(response.body as NodeWebReadableStream<Uint8Array> | null, tempPath);
+	} catch (error) {
+		await rm(tempPath, { force: true });
+		throw new DownloadError(
+			"download-failed",
+			`Download failed for ${options.url} while writing the response body: ${describeFailure(error)}.${proxyLimitationNote(env)}`,
+		);
+	}
+
+	if (actualSha256 !== expectedSha256) {
+		await rm(tempPath, { force: true });
+		throw new ChecksumMismatchError({ actualSha256, expectedSha256, url: options.url });
+	}
+
+	await rename(tempPath, options.destination);
+	return options.destination;
+}
+
+export function resolveDefaultManifestsDir(): string {
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "manifests");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseManifestAsset(value: unknown, manifestName: string, platformKey: string): ManifestAsset {
+	if (!isRecord(value) || typeof value["url"] !== "string" || typeof value["sha256"] !== "string") {
+		throw new Error(`Manifest "${manifestName}" platform "${platformKey}" must pin both url and sha256 strings.`);
+	}
+	return { sha256: value["sha256"], url: value["url"] };
+}
+
+export function parseAssetManifest(raw: string, manifestName: string): AssetManifest {
+	const data: unknown = JSON.parse(raw);
+	if (!isRecord(data) || typeof data["name"] !== "string" || typeof data["version"] !== "string" || !isRecord(data["platforms"])) {
+		throw new Error(`Manifest "${manifestName}" must declare name, version, and a platforms object.`);
+	}
+	const platforms: Record<string, ManifestAsset> = {};
+	for (const [platformKey, asset] of Object.entries(data["platforms"])) {
+		platforms[platformKey] = parseManifestAsset(asset, manifestName, platformKey);
+	}
+	return { name: data["name"], platforms, version: data["version"] };
+}
+
+export async function loadAssetManifest(manifestName: string, manifestsDir?: string): Promise<AssetManifest> {
+	const directory = manifestsDir ?? resolveDefaultManifestsDir();
+	const raw = await readFile(join(directory, `${manifestName}.json`), "utf8");
+	return parseAssetManifest(raw, manifestName);
+}
+
+export async function downloadFromManifest(options: DownloadFromManifestOptions): Promise<string> {
+	const manifest = await loadAssetManifest(options.manifestName, options.manifestsDir);
+	const asset = manifest.platforms[options.platformKey];
+	if (asset === undefined) {
+		throw new UnsupportedPlatformError({
+			availablePlatforms: Object.keys(manifest.platforms),
+			manifestName: options.manifestName,
+			platformKey: options.platformKey,
+		});
+	}
+	const destination = join(options.destinationDir, basename(new URL(asset.url).pathname));
+	return downloadChecksummedAsset({
+		destination,
+		sha256: asset.sha256,
+		url: asset.url,
+		...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+		...(options.env === undefined ? {} : { env: options.env }),
+	});
+}

package/packages/omo-codex/plugin/components/bootstrap/src/environment.ts

@@ -0,0 +1,286 @@
+import { stat } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import { acquireLock, DEFAULT_LOCK_STALE_MS, resolveLockPath, resolveStatePath } from "../../../scripts/auto-update-state.mjs";
+
+export type InstallFlow = "npx-local" | "marketplace" | "unknown";
+
+export type ConfigSourceSignal = "npx-local" | "marketplace" | "unparsable";
+
+export interface DetectInstallFlowOptions {
+	readonly pluginRoot: string;
+	readonly configToml?: string;
+	readonly marketplaceName?: string;
+}
+
+export interface InstallFlowDetection {
+	readonly flow: InstallFlow;
+	readonly snapshotPresent: boolean;
+	readonly configSource: string | undefined;
+	readonly configSignal: ConfigSourceSignal | undefined;
+	readonly reason: string;
+}
+
+export const INSTALL_SNAPSHOT_FILENAME = "lazycodex-install.json";
+
+const DEFAULT_MARKETPLACE_NAME = "sisyphuslabs";
+const MAX_CODEX_HOME_WALK_UP_LEVELS = 6;
+
+export async function detectInstallFlowDetailed(options: DetectInstallFlowOptions): Promise<InstallFlowDetection> {
+	const marketplaceName = options.marketplaceName ?? DEFAULT_MARKETPLACE_NAME;
+	const snapshotPresent = await isFile(join(options.pluginRoot, INSTALL_SNAPSHOT_FILENAME));
+	const snapshotSignal: InstallFlow = snapshotPresent ? "npx-local" : "marketplace";
+	const snapshotReason = snapshotPresent
+		? `${INSTALL_SNAPSHOT_FILENAME} present at plugin root (written only by the npx installer)`
+		: `${INSTALL_SNAPSHOT_FILENAME} absent from plugin root`;
+	const scan = options.configToml === undefined ? { kind: "absent" as const } : scanMarketplaceSource(options.configToml, marketplaceName);
+
+	if (scan.kind === "absent") {
+		return {
+			configSignal: undefined,
+			configSource: undefined,
+			flow: snapshotSignal,
+			reason: `${snapshotReason}; no [marketplaces.${marketplaceName}] source to cross-check`,
+			snapshotPresent,
+		};
+	}
+	if (scan.kind === "unparsable") {
+		return {
+			configSignal: "unparsable",
+			configSource: undefined,
+			flow: "unknown",
+			reason: `${snapshotReason}; [marketplaces.${marketplaceName}] source value is unparsable`,
+			snapshotPresent,
+		};
+	}
+	const configSignal = classifyMarketplaceSource(scan.source);
+	if (configSignal === "unparsable") {
+		return {
+			configSignal,
+			configSource: scan.source,
+			flow: "unknown",
+			reason: `${snapshotReason}; marketplace source ${JSON.stringify(scan.source)} is neither a local absolute path nor a git URL`,
+			snapshotPresent,
+		};
+	}
+	if (configSignal !== snapshotSignal) {
+		return {
+			configSignal,
+			configSource: scan.source,
+			flow: "unknown",
+			reason: `${snapshotReason}, but marketplace source ${JSON.stringify(scan.source)} indicates ${configSignal}; signals disagree`,
+			snapshotPresent,
+		};
+	}
+	return {
+		configSignal,
+		configSource: scan.source,
+		flow: snapshotSignal,
+		reason: `${snapshotReason}; marketplace source ${JSON.stringify(scan.source)} agrees`,
+		snapshotPresent,
+	};
+}
+
+export async function detectInstallFlow(options: DetectInstallFlowOptions): Promise<InstallFlow> {
+	return (await detectInstallFlowDetailed(options)).flow;
+}
+
+export interface DetectInstallFlowFromEnvironmentOptions {
+	readonly pluginRoot: string;
+	readonly env: Record<string, string | undefined>;
+	readonly marketplaceName?: string;
+}
+
+export async function detectInstallFlowFromEnvironment(
+	options: DetectInstallFlowFromEnvironmentOptions,
+): Promise<InstallFlowDetection> {
+	const home = await resolveCodexHome({ env: options.env, pluginRoot: options.pluginRoot });
+	const configToml = await readOptionalFile(join(home.path, "config.toml"));
+	return detectInstallFlowDetailed({
+		pluginRoot: options.pluginRoot,
+		...(configToml === undefined ? {} : { configToml }),
+		...(options.marketplaceName === undefined ? {} : { marketplaceName: options.marketplaceName }),
+	});
+}
+
+export async function detectInstallFlowForTest(pluginRoot: string): Promise<InstallFlow> {
+	const home = await resolveCodexHome({ env: {}, pluginRoot });
+	const configToml = home.source === "walk-up" ? await readOptionalFile(join(home.path, "config.toml")) : undefined;
+	return detectInstallFlow({ pluginRoot, ...(configToml === undefined ? {} : { configToml }) });
+}
+
+export type CodexHomeSource = "env" | "walk-up" | "default";
+
+export interface CodexHomeResolution {
+	readonly path: string;
+	readonly source: CodexHomeSource;
+}
+
+export interface ResolveCodexHomeOptions {
+	readonly env: Record<string, string | undefined>;
+	readonly pluginRoot?: string;
+}
+
+export async function resolveCodexHome(options: ResolveCodexHomeOptions): Promise<CodexHomeResolution> {
+	const envHome = options.env["CODEX_HOME"]?.trim();
+	if (envHome !== undefined && envHome.length > 0) {
+		return { path: resolve(envHome), source: "env" };
+	}
+	if (options.pluginRoot !== undefined) {
+		let current = resolve(options.pluginRoot);
+		for (let level = 0; level < MAX_CODEX_HOME_WALK_UP_LEVELS; level += 1) {
+			const parent = dirname(current);
+			if (parent === current) break;
+			current = parent;
+			if (await isFile(join(current, "config.toml"))) {
+				return { path: current, source: "walk-up" };
+			}
+		}
+	}
+	return { path: join(homedir(), ".codex"), source: "default" };
+}
+
+export interface BootstrapLocksOptions {
+	readonly pluginData: string;
+	readonly env: Record<string, string | undefined>;
+	readonly now?: number;
+	readonly staleMs?: number;
+}
+
+export interface BootstrapLockHandle {
+	readonly statePath: string;
+	readonly bootstrapLockPath: string;
+	readonly autoUpdateLockPath: string;
+	readonly release: () => Promise<void>;
+}
+
+export function resolveBootstrapStatePath(pluginData: string): string {
+	return join(pluginData, "bootstrap", "state.json");
+}
+
+export function resolveBootstrapLockPath(pluginData: string): string {
+	return `${resolveBootstrapStatePath(pluginData)}.lock`;
+}
+
+export async function bootstrapLocks(options: BootstrapLocksOptions): Promise<BootstrapLockHandle | null> {
+	const now = options.now ?? Date.now();
+	const staleMs = options.staleMs ?? DEFAULT_LOCK_STALE_MS;
+	const statePath = resolveBootstrapStatePath(options.pluginData);
+	const bootstrapLockPath = resolveBootstrapLockPath(options.pluginData);
+	const autoUpdateLockPath = resolveLockPath(options.env, resolveStatePath(options.env));
+
+	const bootstrapLock = await acquireLock(bootstrapLockPath, now, staleMs);
+	if (bootstrapLock === null) return null;
+	if (autoUpdateLockPath === bootstrapLockPath) {
+		return { autoUpdateLockPath, bootstrapLockPath, release: () => bootstrapLock.release(), statePath };
+	}
+	const autoUpdateLock = await acquireLock(autoUpdateLockPath, now, staleMs);
+	if (autoUpdateLock === null) {
+		await bootstrapLock.release();
+		return null;
+	}
+	return {
+		autoUpdateLockPath,
+		bootstrapLockPath,
+		release: async () => {
+			await autoUpdateLock.release();
+			await bootstrapLock.release();
+		},
+		statePath,
+	};
+}
+
+type MarketplaceSourceScan = { readonly kind: "absent" } | { readonly kind: "unparsable" } | { readonly kind: "source"; readonly source: string };
+
+function scanMarketplaceSource(configToml: string, marketplaceName: string): MarketplaceSourceScan {
+	const expectedHeaders = new Set([`marketplaces.${marketplaceName}`, `marketplaces.${JSON.stringify(marketplaceName)}`]);
+	let inMarketplaceSection = false;
+	for (const line of configToml.split("\n")) {
+		const header = parseTomlHeader(line);
+		if (header !== null) {
+			inMarketplaceSection = expectedHeaders.has(header);
+			continue;
+		}
+		if (!inMarketplaceSection) continue;
+		const valueText = parseSourceAssignment(line);
+		if (valueText === null) continue;
+		const source = parseTomlStringValue(valueText);
+		return source === undefined ? { kind: "unparsable" } : { kind: "source", source };
+	}
+	return { kind: "absent" };
+}
+
+function parseTomlHeader(line: string): string | null {
+	const trimmed = line.trim();
+	if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return null;
+	if (trimmed.startsWith("[[")) return null;
+	return trimmed.slice(1, -1).trim();
+}
+
+function parseSourceAssignment(line: string): string | null {
+	const match = /^\s*source\s*=\s*(.+)$/.exec(line);
+	return match === null ? null : (match[1] ?? null);
+}
+
+function parseTomlStringValue(valueText: string): string | undefined {
+	const trimmed = valueText.trim();
+	if (trimmed.startsWith('"')) return parseLeadingJsonString(trimmed);
+	if (trimmed.startsWith("'")) {
+		const closingIndex = trimmed.indexOf("'", 1);
+		return closingIndex === -1 ? undefined : trimmed.slice(1, closingIndex);
+	}
+	return undefined;
+}
+
+function parseLeadingJsonString(value: string): string | undefined {
+	let escaped = false;
+	for (let index = 1; index < value.length; index += 1) {
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		const char = value[index];
+		if (char === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (char === '"') {
+			try {
+				const parsed: unknown = JSON.parse(value.slice(0, index + 1));
+				return typeof parsed === "string" ? parsed : undefined;
+			} catch {
+				return undefined;
+			}
+		}
+	}
+	return undefined;
+}
+
+function classifyMarketplaceSource(source: string): ConfigSourceSignal {
+	const trimmed = source.trim();
+	if (trimmed.length === 0) return "unparsable";
+	if (/^(https?|ssh|git):\/\//i.test(trimmed) || trimmed.startsWith("git@")) return "marketplace";
+	if (trimmed.startsWith("/") || trimmed.startsWith("~") || trimmed.startsWith("\\\\") || /^[A-Za-z]:[\\/]/.test(trimmed)) {
+		return "npx-local";
+	}
+	if (trimmed.toLowerCase().endsWith(".git")) return "marketplace";
+	return "unparsable";
+}
+
+async function isFile(path: string): Promise<boolean> {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+
+async function readOptionalFile(path: string): Promise<string | undefined> {
+	try {
+		return await readFile(path, "utf8");
+	} catch {
+		return undefined;
+	}
+}