@asterxsk/kiln 0.1.0 → 0.2.0

package/agent/extensions/pi-web-access/content-find.ts

@@ -1,139 +1,139 @@
-export type FindMode = "exact" | "case-insensitive" | "fuzzy";
-
-const CONTEXT_CHARS = 400;
-const MAX_OUTPUT_CHARS = 20_000;
-
-interface Match {
-	query: string;
-	start: number;
-	end: number;
-}
-
-interface Range {
-	start: number;
-	end: number;
-	matches: Match[];
-}
-
-function normalize(value: string): string {
-	return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLocaleLowerCase();
-}
-
-function editDistanceWithin(left: string, right: string, maximum: number): boolean {
-	if (Math.abs(left.length - right.length) > maximum) return false;
-	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
-	for (let i = 1; i <= left.length; i++) {
-		const current = [i];
-		let rowMinimum = i;
-		for (let j = 1; j <= right.length; j++) {
-			const value = Math.min(
-				(previous[j] ?? 0) + 1,
-				(current[j - 1] ?? 0) + 1,
-				(previous[j - 1] ?? 0) + (left[i - 1] === right[j - 1] ? 0 : 1),
-			);
-			current[j] = value;
-			rowMinimum = Math.min(rowMinimum, value);
-		}
-		if (rowMinimum > maximum) return false;
-		previous = current;
-	}
-	return (previous[right.length] ?? maximum + 1) <= maximum;
-}
-
-function literalMatches(text: string, query: string, caseInsensitive: boolean): Match[] {
-	const haystack = caseInsensitive ? text.toLocaleLowerCase() : text;
-	const needle = caseInsensitive ? query.toLocaleLowerCase() : query;
-	const matches: Match[] = [];
-	for (let start = haystack.indexOf(needle); start >= 0; start = haystack.indexOf(needle, start + Math.max(needle.length, 1))) {
-		matches.push({ query, start, end: start + query.length });
-	}
-	return matches;
-}
-
-function fuzzyMatches(text: string, query: string): Match[] {
-	const queryTokens = normalize(query).match(/[\p{L}\p{N}]+/gu) ?? [];
-	if (queryTokens.length === 0) return [];
-	const matches: Match[] = [];
-	const paragraphs = /[^\n]+(?:\n(?!\n)[^\n]+)*/g;
-	for (const paragraph of text.matchAll(paragraphs)) {
-		const paragraphText = paragraph[0];
-		if (paragraphText.trim().length === 0 || paragraph.index === undefined) continue;
-		const tokens = [...paragraphText.matchAll(/[\p{L}\p{N}]+/gu)];
-		const matched = queryTokens.filter(queryToken => tokens.some(token => {
-			const candidate = normalize(token[0]);
-			const maximum = queryToken.length >= 9 ? 2 : queryToken.length >= 5 ? 1 : 0;
-			return editDistanceWithin(queryToken, candidate, maximum);
-		}));
-		const required = queryTokens.length === 1 ? 1 : Math.ceil(queryTokens.length * 0.6);
-		if (matched.length < required) continue;
-		const first = tokens.find(token => matched.some(queryToken => {
-			const maximum = queryToken.length >= 9 ? 2 : queryToken.length >= 5 ? 1 : 0;
-			return editDistanceWithin(queryToken, normalize(token[0]), maximum);
-		}));
-		const start = paragraph.index + (first?.index ?? 0);
-		matches.push({ query, start, end: start + (first?.[0].length ?? query.length) });
-	}
-	return matches;
-}
-
-function mergeRanges(textLength: number, matches: Match[]): Range[] {
-	const ranges: Range[] = [];
-	for (const match of [...matches].sort((left, right) => left.start - right.start)) {
-		const start = Math.max(0, match.start - CONTEXT_CHARS);
-		const end = Math.min(textLength, match.end + CONTEXT_CHARS);
-		const previous = ranges.at(-1);
-		if (previous && start <= previous.end) {
-			previous.end = Math.max(previous.end, end);
-			previous.matches.push(match);
-		} else {
-			ranges.push({ start, end, matches: [match] });
-		}
-	}
-	return ranges;
-}
-
-export function findContent(
-	text: string,
-	queries: string[],
-	mode: FindMode,
-): { text: string; matchCount: number; returnedMatches: number; queryResults: Array<{ query: string; matchCount: number }> } {
-	const normalizedQueries = [...new Set(queries.map(query => query.trim()).filter(Boolean))];
-	const matches = normalizedQueries.flatMap(query => mode === "fuzzy"
-		? fuzzyMatches(text, query)
-		: literalMatches(text, query, mode === "case-insensitive"));
-	const queryResults = normalizedQueries.map(query => ({
-		query,
-		matchCount: matches.filter(match => match.query === query).length,
-	}));
-
-	const heading = matches.length > 0 ? `Text matches (${mode})` : `Text matches (${mode}): no matches`;
-	const sections = [heading];
-	let formattedLength = heading.length;
-	let returnedMatches = 0;
-	for (const range of mergeRanges(text.length, matches)) {
-		const prefix = range.start > 0 ? "…" : "";
-		const suffix = range.end < text.length ? "…" : "";
-		const snippet = `${prefix}${text.slice(range.start, range.end).replace(/\s+/g, " ").trim()}${suffix}`;
-		const counts = [...new Set(range.matches.map(match => match.query))]
-			.map(query => `\"${query}\" ×${range.matches.filter(match => match.query === query).length}`)
-			.join(", ");
-		const section = `${sections.length}. ${counts}\n${snippet}`;
-		if (formattedLength + 2 + section.length > MAX_OUTPUT_CHARS) break;
-		sections.push(section);
-		formattedLength += 2 + section.length;
-		returnedMatches += range.matches.length;
-	}
-
-	const missing = queryResults.filter(result => result.matchCount === 0).map(result => `\"${result.query}\"`);
-	const footer = [
-		...(missing.length > 0 ? [`No matches: ${missing.join(", ")}`] : []),
-		...(returnedMatches < matches.length ? [`Showing ${returnedMatches} of ${matches.length} matches.`] : []),
-	];
-	for (const section of footer) {
-		if (formattedLength + 2 + section.length > MAX_OUTPUT_CHARS) break;
-		sections.push(section);
-		formattedLength += 2 + section.length;
-	}
-
-	return { text: sections.join("\n\n"), matchCount: matches.length, returnedMatches, queryResults };
-}
+export type FindMode = "exact" | "case-insensitive" | "fuzzy";
+
+const CONTEXT_CHARS = 400;
+const MAX_OUTPUT_CHARS = 20_000;
+
+interface Match {
+	query: string;
+	start: number;
+	end: number;
+}
+
+interface Range {
+	start: number;
+	end: number;
+	matches: Match[];
+}
+
+function normalize(value: string): string {
+	return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLocaleLowerCase();
+}
+
+function editDistanceWithin(left: string, right: string, maximum: number): boolean {
+	if (Math.abs(left.length - right.length) > maximum) return false;
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= left.length; i++) {
+		const current = [i];
+		let rowMinimum = i;
+		for (let j = 1; j <= right.length; j++) {
+			const value = Math.min(
+				(previous[j] ?? 0) + 1,
+				(current[j - 1] ?? 0) + 1,
+				(previous[j - 1] ?? 0) + (left[i - 1] === right[j - 1] ? 0 : 1),
+			);
+			current[j] = value;
+			rowMinimum = Math.min(rowMinimum, value);
+		}
+		if (rowMinimum > maximum) return false;
+		previous = current;
+	}
+	return (previous[right.length] ?? maximum + 1) <= maximum;
+}
+
+function literalMatches(text: string, query: string, caseInsensitive: boolean): Match[] {
+	const haystack = caseInsensitive ? text.toLocaleLowerCase() : text;
+	const needle = caseInsensitive ? query.toLocaleLowerCase() : query;
+	const matches: Match[] = [];
+	for (let start = haystack.indexOf(needle); start >= 0; start = haystack.indexOf(needle, start + Math.max(needle.length, 1))) {
+		matches.push({ query, start, end: start + query.length });
+	}
+	return matches;
+}
+
+function fuzzyMatches(text: string, query: string): Match[] {
+	const queryTokens = normalize(query).match(/[\p{L}\p{N}]+/gu) ?? [];
+	if (queryTokens.length === 0) return [];
+	const matches: Match[] = [];
+	const paragraphs = /[^\n]+(?:\n(?!\n)[^\n]+)*/g;
+	for (const paragraph of text.matchAll(paragraphs)) {
+		const paragraphText = paragraph[0];
+		if (paragraphText.trim().length === 0 || paragraph.index === undefined) continue;
+		const tokens = [...paragraphText.matchAll(/[\p{L}\p{N}]+/gu)];
+		const matched = queryTokens.filter(queryToken => tokens.some(token => {
+			const candidate = normalize(token[0]);
+			const maximum = queryToken.length >= 9 ? 2 : queryToken.length >= 5 ? 1 : 0;
+			return editDistanceWithin(queryToken, candidate, maximum);
+		}));
+		const required = queryTokens.length === 1 ? 1 : Math.ceil(queryTokens.length * 0.6);
+		if (matched.length < required) continue;
+		const first = tokens.find(token => matched.some(queryToken => {
+			const maximum = queryToken.length >= 9 ? 2 : queryToken.length >= 5 ? 1 : 0;
+			return editDistanceWithin(queryToken, normalize(token[0]), maximum);
+		}));
+		const start = paragraph.index + (first?.index ?? 0);
+		matches.push({ query, start, end: start + (first?.[0].length ?? query.length) });
+	}
+	return matches;
+}
+
+function mergeRanges(textLength: number, matches: Match[]): Range[] {
+	const ranges: Range[] = [];
+	for (const match of [...matches].sort((left, right) => left.start - right.start)) {
+		const start = Math.max(0, match.start - CONTEXT_CHARS);
+		const end = Math.min(textLength, match.end + CONTEXT_CHARS);
+		const previous = ranges.at(-1);
+		if (previous && start <= previous.end) {
+			previous.end = Math.max(previous.end, end);
+			previous.matches.push(match);
+		} else {
+			ranges.push({ start, end, matches: [match] });
+		}
+	}
+	return ranges;
+}
+
+export function findContent(
+	text: string,
+	queries: string[],
+	mode: FindMode,
+): { text: string; matchCount: number; returnedMatches: number; queryResults: Array<{ query: string; matchCount: number }> } {
+	const normalizedQueries = [...new Set(queries.map(query => query.trim()).filter(Boolean))];
+	const matches = normalizedQueries.flatMap(query => mode === "fuzzy"
+		? fuzzyMatches(text, query)
+		: literalMatches(text, query, mode === "case-insensitive"));
+	const queryResults = normalizedQueries.map(query => ({
+		query,
+		matchCount: matches.filter(match => match.query === query).length,
+	}));
+
+	const heading = matches.length > 0 ? `Text matches (${mode})` : `Text matches (${mode}): no matches`;
+	const sections = [heading];
+	let formattedLength = heading.length;
+	let returnedMatches = 0;
+	for (const range of mergeRanges(text.length, matches)) {
+		const prefix = range.start > 0 ? "…" : "";
+		const suffix = range.end < text.length ? "…" : "";
+		const snippet = `${prefix}${text.slice(range.start, range.end).replace(/\s+/g, " ").trim()}${suffix}`;
+		const counts = [...new Set(range.matches.map(match => match.query))]
+			.map(query => `\"${query}\" ×${range.matches.filter(match => match.query === query).length}`)
+			.join(", ");
+		const section = `${sections.length}. ${counts}\n${snippet}`;
+		if (formattedLength + 2 + section.length > MAX_OUTPUT_CHARS) break;
+		sections.push(section);
+		formattedLength += 2 + section.length;
+		returnedMatches += range.matches.length;
+	}
+
+	const missing = queryResults.filter(result => result.matchCount === 0).map(result => `\"${result.query}\"`);
+	const footer = [
+		...(missing.length > 0 ? [`No matches: ${missing.join(", ")}`] : []),
+		...(returnedMatches < matches.length ? [`Showing ${returnedMatches} of ${matches.length} matches.`] : []),
+	];
+	for (const section of footer) {
+		if (formattedLength + 2 + section.length > MAX_OUTPUT_CHARS) break;
+		sections.push(section);
+		formattedLength += 2 + section.length;
+	}
+
+	return { text: sections.join("\n\n"), matchCount: matches.length, returnedMatches, queryResults };
+}

package/agent/extensions/pi-web-access/credential-source.ts

@@ -1,191 +1,191 @@
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
-
-const execAsync = promisify(exec);
-const COMMAND_TIMEOUT_MS = 5_000;
-const MAX_CREDENTIAL_BYTES = 16_384;
-const ENV_SOURCE = /^\$(?:([A-Za-z_][A-Za-z0-9_]*)|\{([A-Za-z_][A-Za-z0-9_]*)\})$/;
-const OP_SESSION_NAME = /^OP_SESSION_[A-Za-z0-9_]+$/;
-const COMMAND_ENVIRONMENT_NAMES = [
-	"HOME",
-	"USER",
-	"LOGNAME",
-	"PATH",
-	"LANG",
-	"LC_ALL",
-	"LC_CTYPE",
-	"TERM",
-	"TMPDIR",
-	"XDG_CONFIG_HOME",
-	"XDG_RUNTIME_DIR",
-	"DBUS_SESSION_BUS_ADDRESS",
-	"SSH_AUTH_SOCK",
-	"WSL_DISTRO_NAME",
-	"WSL_INTEROP",
-] as const;
-
-export type CredentialFailureCategory =
-	| "invalid-source"
-	| "command-failed"
-	| "command-timeout"
-	| "command-aborted"
-	| "command-empty"
-	| "command-invalid-output"
-	| "command-output-too-large"
-	| "environment-empty"
-	| "oauth-credential-rejected";
-
-export class CredentialResolutionError extends Error {
-	readonly provider: string;
-	readonly category: CredentialFailureCategory;
-
-	constructor(provider: string, category: CredentialFailureCategory) {
-		const suffix =
-			category === "command-aborted" ? "aborted" :
-			category === "oauth-credential-rejected" ? "OAuth token exchange rejected the credentials" :
-			category;
-		super(`${provider} credential resolution failed: ${suffix}`);
-		this.name = "CredentialResolutionError";
-		this.provider = provider;
-		this.category = category;
-	}
-}
-
-export interface CredentialCommandResult {
-	stdout: string | Buffer;
-}
-
-export interface CredentialCommandOptions {
-	signal?: AbortSignal;
-	timeoutMs: number;
-	maxOutputBytes: number;
-	environment: Record<string, string>;
-}
-
-export type CredentialCommandRunner = (
-	command: string,
-	options: CredentialCommandOptions,
-) => Promise<CredentialCommandResult>;
-
-export interface CredentialOptions {
-	provider: string;
-	configuredValue?: unknown;
-	environmentValue?: unknown;
-	environment?: Record<string, string | undefined>;
-	signal?: AbortSignal;
-	runCommand?: CredentialCommandRunner;
-}
-
-export function redactCredential(text: string, credential: string | null | undefined): string {
-	return credential ? text.split(credential).join("[redacted]") : text;
-}
-
-function normalize(value: unknown): string | null {
-	if (typeof value !== "string") return null;
-	const normalized = value.trim();
-	return normalized.length > 0 ? normalized : null;
-}
-
-function commandEnvironment(source: Record<string, string | undefined>): Record<string, string> {
-	const environment: Record<string, string> = {};
-	for (const name of COMMAND_ENVIRONMENT_NAMES) {
-		const value = source[name];
-		if (value !== undefined) environment[name] = value;
-	}
-	for (const [name, value] of Object.entries(source)) {
-		if (value !== undefined && OP_SESSION_NAME.test(name)) environment[name] = value;
-	}
-	return environment;
-}
-
-function configuredSource(options: CredentialOptions): string | null {
-	return normalize(options.configuredValue);
-}
-
-function explicitEnvironmentName(source: string): string | null {
-	const match = source.match(ENV_SOURCE);
-	return match ? match[1] ?? match[2] : null;
-}
-
-function escapedSource(source: string): string | null {
-	if (source.startsWith("$$") || source.startsWith("$!")) return source.slice(1);
-	return null;
-}
-
-function isMalformedExplicitSource(source: string): boolean {
-	return source.startsWith("$") && escapedSource(source) === null && explicitEnvironmentName(source) === null;
-}
-
-async function defaultRunCommand(
-	command: string,
-	options: CredentialCommandOptions,
-): Promise<CredentialCommandResult> {
-	const result = await execAsync(command, {
-		encoding: "utf8",
-		env: options.environment,
-		maxBuffer: options.maxOutputBytes + 1,
-		signal: options.signal,
-		timeout: options.timeoutMs,
-		windowsHide: true,
-	});
-	return { stdout: result.stdout };
-}
-
-function commandFailureCategory(error: unknown, signal?: AbortSignal): CredentialFailureCategory {
-	if (signal?.aborted) return "command-aborted";
-	if (error && typeof error === "object") {
-		const code = (error as { code?: string }).code;
-		if (code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return "command-output-too-large";
-		if ((error as { killed?: boolean }).killed || code === "ETIMEDOUT") return "command-timeout";
-	}
-	return "command-failed";
-}
-
-export function hasCredentialSource(options: CredentialOptions): boolean {
-	const source = configuredSource(options);
-	if (source?.startsWith("!")) return true;
-	if (source?.startsWith("$")) return true;
-	return normalize(options.environmentValue) !== null || source !== null;
-}
-
-export async function resolveCredential(options: CredentialOptions): Promise<string | null> {
-	const source = configuredSource(options);
-	const escaped = source ? escapedSource(source) : null;
-	if (escaped !== null) return escaped;
-	if (source?.startsWith("!")) {
-		const command = source.slice(1).trim();
-		if (!command) throw new CredentialResolutionError(options.provider, "invalid-source");
-		let result: CredentialCommandResult;
-		try {
-			result = await (options.runCommand ?? defaultRunCommand)(command, {
-				signal: options.signal,
-				timeoutMs: COMMAND_TIMEOUT_MS,
-				maxOutputBytes: MAX_CREDENTIAL_BYTES,
-				environment: commandEnvironment(options.environment ?? process.env),
-			});
-		} catch (error) {
-			throw new CredentialResolutionError(options.provider, commandFailureCategory(error, options.signal));
-		}
-		const stdout = Buffer.isBuffer(result.stdout) ? result.stdout.toString("utf8") : result.stdout;
-		if (Buffer.byteLength(stdout, "utf8") > MAX_CREDENTIAL_BYTES) {
-			throw new CredentialResolutionError(options.provider, "command-output-too-large");
-		}
-		const value = stdout.trim();
-		if (!value) throw new CredentialResolutionError(options.provider, "command-empty");
-		if (/[\0-\x1f\x7f]/.test(value)) {
-			throw new CredentialResolutionError(options.provider, "command-invalid-output");
-		}
-		return value;
-	}
-	if (source && isMalformedExplicitSource(source)) {
-		throw new CredentialResolutionError(options.provider, "invalid-source");
-	}
-	if (source?.startsWith("$")) {
-		const name = explicitEnvironmentName(source);
-		if (!name) throw new CredentialResolutionError(options.provider, "invalid-source");
-		const value = normalize((options.environment ?? process.env)[name]);
-		if (!value) throw new CredentialResolutionError(options.provider, "environment-empty");
-		return value;
-	}
-	return normalize(options.environmentValue) ?? source;
-}
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+const COMMAND_TIMEOUT_MS = 5_000;
+const MAX_CREDENTIAL_BYTES = 16_384;
+const ENV_SOURCE = /^\$(?:([A-Za-z_][A-Za-z0-9_]*)|\{([A-Za-z_][A-Za-z0-9_]*)\})$/;
+const OP_SESSION_NAME = /^OP_SESSION_[A-Za-z0-9_]+$/;
+const COMMAND_ENVIRONMENT_NAMES = [
+	"HOME",
+	"USER",
+	"LOGNAME",
+	"PATH",
+	"LANG",
+	"LC_ALL",
+	"LC_CTYPE",
+	"TERM",
+	"TMPDIR",
+	"XDG_CONFIG_HOME",
+	"XDG_RUNTIME_DIR",
+	"DBUS_SESSION_BUS_ADDRESS",
+	"SSH_AUTH_SOCK",
+	"WSL_DISTRO_NAME",
+	"WSL_INTEROP",
+] as const;
+
+export type CredentialFailureCategory =
+	| "invalid-source"
+	| "command-failed"
+	| "command-timeout"
+	| "command-aborted"
+	| "command-empty"
+	| "command-invalid-output"
+	| "command-output-too-large"
+	| "environment-empty"
+	| "oauth-credential-rejected";
+
+export class CredentialResolutionError extends Error {
+	readonly provider: string;
+	readonly category: CredentialFailureCategory;
+
+	constructor(provider: string, category: CredentialFailureCategory) {
+		const suffix =
+			category === "command-aborted" ? "aborted" :
+			category === "oauth-credential-rejected" ? "OAuth token exchange rejected the credentials" :
+			category;
+		super(`${provider} credential resolution failed: ${suffix}`);
+		this.name = "CredentialResolutionError";
+		this.provider = provider;
+		this.category = category;
+	}
+}
+
+export interface CredentialCommandResult {
+	stdout: string | Buffer;
+}
+
+export interface CredentialCommandOptions {
+	signal?: AbortSignal;
+	timeoutMs: number;
+	maxOutputBytes: number;
+	environment: Record<string, string>;
+}
+
+export type CredentialCommandRunner = (
+	command: string,
+	options: CredentialCommandOptions,
+) => Promise<CredentialCommandResult>;
+
+export interface CredentialOptions {
+	provider: string;
+	configuredValue?: unknown;
+	environmentValue?: unknown;
+	environment?: Record<string, string | undefined>;
+	signal?: AbortSignal;
+	runCommand?: CredentialCommandRunner;
+}
+
+export function redactCredential(text: string, credential: string | null | undefined): string {
+	return credential ? text.split(credential).join("[redacted]") : text;
+}
+
+function normalize(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const normalized = value.trim();
+	return normalized.length > 0 ? normalized : null;
+}
+
+function commandEnvironment(source: Record<string, string | undefined>): Record<string, string> {
+	const environment: Record<string, string> = {};
+	for (const name of COMMAND_ENVIRONMENT_NAMES) {
+		const value = source[name];
+		if (value !== undefined) environment[name] = value;
+	}
+	for (const [name, value] of Object.entries(source)) {
+		if (value !== undefined && OP_SESSION_NAME.test(name)) environment[name] = value;
+	}
+	return environment;
+}
+
+function configuredSource(options: CredentialOptions): string | null {
+	return normalize(options.configuredValue);
+}
+
+function explicitEnvironmentName(source: string): string | null {
+	const match = source.match(ENV_SOURCE);
+	return match ? match[1] ?? match[2] : null;
+}
+
+function escapedSource(source: string): string | null {
+	if (source.startsWith("$$") || source.startsWith("$!")) return source.slice(1);
+	return null;
+}
+
+function isMalformedExplicitSource(source: string): boolean {
+	return source.startsWith("$") && escapedSource(source) === null && explicitEnvironmentName(source) === null;
+}
+
+async function defaultRunCommand(
+	command: string,
+	options: CredentialCommandOptions,
+): Promise<CredentialCommandResult> {
+	const result = await execAsync(command, {
+		encoding: "utf8",
+		env: options.environment,
+		maxBuffer: options.maxOutputBytes + 1,
+		signal: options.signal,
+		timeout: options.timeoutMs,
+		windowsHide: true,
+	});
+	return { stdout: result.stdout };
+}
+
+function commandFailureCategory(error: unknown, signal?: AbortSignal): CredentialFailureCategory {
+	if (signal?.aborted) return "command-aborted";
+	if (error && typeof error === "object") {
+		const code = (error as { code?: string }).code;
+		if (code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return "command-output-too-large";
+		if ((error as { killed?: boolean }).killed || code === "ETIMEDOUT") return "command-timeout";
+	}
+	return "command-failed";
+}
+
+export function hasCredentialSource(options: CredentialOptions): boolean {
+	const source = configuredSource(options);
+	if (source?.startsWith("!")) return true;
+	if (source?.startsWith("$")) return true;
+	return normalize(options.environmentValue) !== null || source !== null;
+}
+
+export async function resolveCredential(options: CredentialOptions): Promise<string | null> {
+	const source = configuredSource(options);
+	const escaped = source ? escapedSource(source) : null;
+	if (escaped !== null) return escaped;
+	if (source?.startsWith("!")) {
+		const command = source.slice(1).trim();
+		if (!command) throw new CredentialResolutionError(options.provider, "invalid-source");
+		let result: CredentialCommandResult;
+		try {
+			result = await (options.runCommand ?? defaultRunCommand)(command, {
+				signal: options.signal,
+				timeoutMs: COMMAND_TIMEOUT_MS,
+				maxOutputBytes: MAX_CREDENTIAL_BYTES,
+				environment: commandEnvironment(options.environment ?? process.env),
+			});
+		} catch (error) {
+			throw new CredentialResolutionError(options.provider, commandFailureCategory(error, options.signal));
+		}
+		const stdout = Buffer.isBuffer(result.stdout) ? result.stdout.toString("utf8") : result.stdout;
+		if (Buffer.byteLength(stdout, "utf8") > MAX_CREDENTIAL_BYTES) {
+			throw new CredentialResolutionError(options.provider, "command-output-too-large");
+		}
+		const value = stdout.trim();
+		if (!value) throw new CredentialResolutionError(options.provider, "command-empty");
+		if (/[\0-\x1f\x7f]/.test(value)) {
+			throw new CredentialResolutionError(options.provider, "command-invalid-output");
+		}
+		return value;
+	}
+	if (source && isMalformedExplicitSource(source)) {
+		throw new CredentialResolutionError(options.provider, "invalid-source");
+	}
+	if (source?.startsWith("$")) {
+		const name = explicitEnvironmentName(source);
+		if (!name) throw new CredentialResolutionError(options.provider, "invalid-source");
+		const value = normalize((options.environment ?? process.env)[name]);
+		if (!value) throw new CredentialResolutionError(options.provider, "environment-empty");
+		return value;
+	}
+	return normalize(options.environmentValue) ?? source;
+}