btca-server 1.0.92 → 1.0.93

package/src/resources/service.ts

@@ -1,25 +1,33 @@
 import { createHash } from 'node:crypto';
 
 import { Config } from '../config/index.ts';
-import { validateGitUrl } from '../validation/index.ts';
+import { parseNpmReference, validateGitUrl } from '../validation/index.ts';
 import { CommonHints } from '../errors.ts';
 
 import { ResourceError, resourceNameToKey } from './helpers.ts';
 import { loadGitResource } from './impls/git.ts';
+import { loadNpmResource } from './impls/npm.ts';
 import {
 	isGitResource,
+	isNpmResource,
 	type ResourceDefinition,
 	type GitResource,
-	type LocalResource
+	type LocalResource,
+	type NpmResource
 } from './schema.ts';
-import type { BtcaFsResource, BtcaGitResourceArgs, BtcaLocalResourceArgs } from './types.ts';
+import type {
+	BtcaFsResource,
+	BtcaGitResourceArgs,
+	BtcaLocalResourceArgs,
+	BtcaNpmResourceArgs
+} from './types.ts';
 
 const ANON_PREFIX = 'anonymous:';
 const ANON_DIRECTORY_PREFIX = 'anonymous-';
 const DEFAULT_ANON_BRANCH = 'main';
 
-export const createAnonymousDirectoryKey = (url: string): string => {
-	const hash = createHash('sha256').update(url).digest('hex').slice(0, 12);
+export const createAnonymousDirectoryKey = (reference: string): string => {
+	const hash = createHash('sha256').update(reference).digest('hex').slice(0, 12);
 	return `${ANON_DIRECTORY_PREFIX}${hash}`;
 };
 
@@ -69,6 +77,25 @@ export namespace Resources {
 		specialAgentInstructions: definition.specialNotes ?? ''
 	});
 
+	const definitionToNpmArgs = (
+		definition: NpmResource,
+		resourcesDirectory: string
+	): BtcaNpmResourceArgs => {
+		const reference = `${definition.package}${definition.version ? `@${definition.version}` : ''}`;
+		return {
+			type: 'npm',
+			name: definition.name,
+			package: definition.package,
+			...(definition.version ? { version: definition.version } : {}),
+			resourcesDirectoryPath: resourcesDirectory,
+			specialAgentInstructions: definition.specialNotes ?? '',
+			ephemeral: isAnonymousResource(definition.name),
+			localDirectoryKey: isAnonymousResource(definition.name)
+				? createAnonymousDirectoryKey(reference)
+				: undefined
+		};
+	};
+
 	const loadLocalResource = (args: BtcaLocalResourceArgs): BtcaFsResource => ({
 		_tag: 'fs-based',
 		name: args.name,
@@ -79,17 +106,28 @@ export namespace Resources {
 		getAbsoluteDirectoryPath: async () => args.path
 	});
 
-	export const createAnonymousResource = (reference: string): GitResource | null => {
-		const gitUrlResult = validateGitUrl(reference);
-		if (!gitUrlResult.valid) return null;
+	export const createAnonymousResource = (reference: string): ResourceDefinition | null => {
+		const npmReference = parseNpmReference(reference);
+		if (npmReference) {
+			return {
+				type: 'npm',
+				name: `${ANON_PREFIX}${npmReference.normalizedReference}`,
+				package: npmReference.packageName,
+				...(npmReference.version ? { version: npmReference.version } : {})
+			};
+		}
 
-		const normalizedUrl = gitUrlResult.value;
-		return {
-			type: 'git',
-			name: `${ANON_PREFIX}${normalizedUrl}`,
-			url: normalizedUrl,
-			branch: DEFAULT_ANON_BRANCH
-		};
+		const gitUrlResult = validateGitUrl(reference);
+		if (gitUrlResult.valid) {
+			const normalizedUrl = gitUrlResult.value;
+			return {
+				type: 'git',
+				name: `${ANON_PREFIX}${normalizedUrl}`,
+				url: normalizedUrl,
+				branch: DEFAULT_ANON_BRANCH
+			};
+		}
+		return null;
 	};
 
 	export const resolveResourceDefinition = (
@@ -116,9 +154,13 @@ export namespace Resources {
 
 				if (isGitResource(definition)) {
 					return loadGitResource(definitionToGitArgs(definition, config.resourcesDirectory, quiet));
-				} else {
-					return loadLocalResource(definitionToLocalArgs(definition));
 				}
+
+				if (isNpmResource(definition)) {
+					return loadNpmResource(definitionToNpmArgs(definition, config.resourcesDirectory));
+				}
+
+				return loadLocalResource(definitionToLocalArgs(definition));
 			}
 		};
 	};

package/src/resources/types.ts

@@ -5,7 +5,7 @@ export type BtcaFsResource = {
 	readonly _tag: 'fs-based';
 	readonly name: string;
 	readonly fsName: string;
-	readonly type: 'git' | 'local';
+	readonly type: 'git' | 'local' | 'npm';
 	readonly repoSubPaths: readonly string[];
 	readonly specialAgentInstructions: string;
 	readonly getAbsoluteDirectoryPath: () => Promise<string>;
@@ -31,3 +31,14 @@ export type BtcaLocalResourceArgs = {
 	readonly path: string;
 	readonly specialAgentInstructions: string;
 };
+
+export type BtcaNpmResourceArgs = {
+	readonly type: 'npm';
+	readonly name: string;
+	readonly package: string;
+	readonly version?: string;
+	readonly resourcesDirectoryPath: string;
+	readonly specialAgentInstructions: string;
+	readonly ephemeral?: boolean;
+	readonly localDirectoryKey?: string;
+};

package/src/stream/service.ts

@@ -1,7 +1,7 @@
 import { stripUserQuestionFromStart, extractCoreQuestion } from '@btca/shared';
 import { Result } from 'better-result';
 
-import { getErrorMessage, getErrorTag } from '../errors.ts';
+import { getErrorHint, getErrorMessage, getErrorTag } from '../errors.ts';
 import { Metrics } from '../metrics/index.ts';
 import type { AgentLoop } from '../agent/loop.ts';
 
@@ -304,7 +304,8 @@ export namespace StreamService {
 									const err: BtcaStreamErrorEvent = {
 										type: 'error',
 										tag: getErrorTag(event.error),
-										message: getErrorMessage(event.error)
+										message: getErrorMessage(event.error),
+										hint: getErrorHint(event.error)
 									};
 									emit(controller, err);
 									break;
@@ -323,7 +324,8 @@ export namespace StreamService {
 							const err: BtcaStreamErrorEvent = {
 								type: 'error',
 								tag: getErrorTag(cause),
-								message: getErrorMessage(cause)
+								message: getErrorMessage(cause),
+								hint: getErrorHint(cause)
 							};
 							emit(controller, err);
 						}

package/src/stream/types.ts

@@ -129,7 +129,8 @@ export const BtcaStreamDoneEventSchema = z.object({
 export const BtcaStreamErrorEventSchema = z.object({
 	type: z.literal('error'),
 	tag: z.string(),
-	message: z.string()
+	message: z.string(),
+	hint: z.string().optional()
 });
 
 export const BtcaStreamEventSchema = z.union([

package/src/validation/index.test.ts

@@ -21,6 +21,30 @@ describe('validateResourceReference', () => {
 		}
 	});
 
+	it('accepts and normalizes npm references', () => {
+		const result = validateResourceReference('npm:@types/node@22.10.1');
+		expect(result.valid).toBe(true);
+		if (result.valid) {
+			expect(result.value).toBe('npm:@types/node@22.10.1');
+		}
+	});
+
+	it('accepts and normalizes npm package URLs', () => {
+		const result = validateResourceReference('https://www.npmjs.com/package/react/v/19.0.0');
+		expect(result.valid).toBe(true);
+		if (result.valid) {
+			expect(result.value).toBe('npm:react@19.0.0');
+		}
+	});
+
+	it('rejects malformed npm package URLs without throwing', () => {
+		const result = validateResourceReference('https://www.npmjs.com/package/%');
+		expect(result.valid).toBe(false);
+		if (!result.valid) {
+			expect(result.error).toContain('Invalid npm reference');
+		}
+	});
+
 	it('rejects invalid resource references', () => {
 		const result = validateResourceReference('not a resource');
 		expect(result.valid).toBe(false);
@@ -40,7 +64,11 @@ describe('validateResourceReference', () => {
 
 describe('validateResourcesArray', () => {
 	it('validates names and URLs together', () => {
-		const result = validateResourcesArray(['svelte', 'https://github.com/sveltejs/svelte.dev']);
+		const result = validateResourcesArray([
+			'svelte',
+			'https://github.com/sveltejs/svelte.dev',
+			'npm:react'
+		]);
 		expect(result.valid).toBe(true);
 	});
 });

package/src/validation/index.ts

@@ -24,6 +24,8 @@ const RESOURCE_NAME_REGEX = /^@?[a-zA-Z0-9][a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0
  * Must not start with hyphen to prevent git option injection.
  */
 const BRANCH_NAME_REGEX = /^[a-zA-Z0-9/_.-]+$/;
+const NPM_PACKAGE_SEGMENT_REGEX = /^[a-z0-9][a-z0-9._-]*$/;
+const NPM_VERSION_OR_TAG_REGEX = /^[^\s/]+$/;
 
 /**
  * Provider/Model names: letters, numbers, dots, underscores, plus, hyphens, forward slashes, colons.
@@ -256,6 +258,134 @@ export const validateGitUrl = (url: string): ValidationResultWithValue<string> =
 	return okWithValue(normalizedUrl);
 };
 
+export type ParsedNpmReference = {
+	packageName: string;
+	version?: string;
+	normalizedReference: string;
+	packageUrl: string;
+};
+
+const isValidNpmPackageName = (name: string): boolean => {
+	if (name.startsWith('@')) {
+		const [scope, pkg, ...rest] = name.split('/');
+		return (
+			rest.length === 0 &&
+			!!scope &&
+			scope.length > 1 &&
+			!!pkg &&
+			NPM_PACKAGE_SEGMENT_REGEX.test(scope.slice(1)) &&
+			NPM_PACKAGE_SEGMENT_REGEX.test(pkg)
+		);
+	}
+
+	if (name.includes('/')) return false;
+	return NPM_PACKAGE_SEGMENT_REGEX.test(name);
+};
+
+const isValidNpmVersionOrTag = (value: string): boolean =>
+	value.length > 0 &&
+	value.length <= LIMITS.BRANCH_NAME_MAX &&
+	NPM_VERSION_OR_TAG_REGEX.test(value);
+
+const splitNpmSpec = (spec: string): { packageName: string; version?: string } | null => {
+	if (!spec) return null;
+	if (spec.startsWith('@')) {
+		const secondAt = spec.indexOf('@', 1);
+		if (secondAt === -1) return { packageName: spec };
+		const packageName = spec.slice(0, secondAt);
+		const version = spec.slice(secondAt + 1);
+		return version ? { packageName, version } : null;
+	}
+
+	const at = spec.lastIndexOf('@');
+	if (at <= 0) return { packageName: spec };
+	const packageName = spec.slice(0, at);
+	const version = spec.slice(at + 1);
+	return version ? { packageName, version } : null;
+};
+
+const encodeNpmPackagePath = (packageName: string): string =>
+	packageName.split('/').map(encodeURIComponent).join('/');
+
+const toNpmReference = (parsed: { packageName: string; version?: string }): ParsedNpmReference => {
+	const normalizedReference = `npm:${parsed.packageName}${parsed.version ? `@${parsed.version}` : ''}`;
+	const packageUrl = `https://www.npmjs.com/package/${encodeNpmPackagePath(parsed.packageName)}${
+		parsed.version ? `/v/${encodeURIComponent(parsed.version)}` : ''
+	}`;
+	return {
+		packageName: parsed.packageName,
+		...(parsed.version ? { version: parsed.version } : {}),
+		normalizedReference,
+		packageUrl
+	};
+};
+
+const safeDecodeUriComponent = (value: string): string | null =>
+	Result.try(() => decodeURIComponent(value)).match({
+		ok: (decoded) => decoded,
+		err: () => null
+	});
+
+const parseNpmSpecReference = (reference: string): ParsedNpmReference | null => {
+	if (!reference.startsWith('npm:')) return null;
+	const spec = reference.slice(4).trim();
+	if (!spec) return null;
+
+	const parsed = splitNpmSpec(spec);
+	if (!parsed || !isValidNpmPackageName(parsed.packageName)) return null;
+	if (parsed.version && !isValidNpmVersionOrTag(parsed.version)) return null;
+
+	return toNpmReference(parsed);
+};
+
+const parseNpmUrlReference = (reference: string): ParsedNpmReference | null => {
+	const parsedUrl = parseUrl(reference).match({
+		ok: (value) => value,
+		err: () => null
+	});
+	if (!parsedUrl) return null;
+	if (parsedUrl.protocol !== 'https:') return null;
+
+	const hostname = parsedUrl.hostname.toLowerCase();
+	if (hostname !== 'npmjs.com' && hostname !== 'www.npmjs.com') return null;
+
+	const segments = parsedUrl.pathname.split('/').filter((segment) => segment.length > 0);
+	if (segments[0] !== 'package') return null;
+
+	const packageParts = segments[1]?.startsWith('@') ? segments.slice(1, 3) : segments.slice(1, 2);
+	if (packageParts.length === 0 || packageParts.some((part) => !part)) return null;
+	const decodedPackageParts = packageParts.map(safeDecodeUriComponent);
+	if (decodedPackageParts.some((part) => !part)) return null;
+	const packageName = decodedPackageParts.join('/');
+	if (!isValidNpmPackageName(packageName)) return null;
+
+	const remainder = segments.slice(1 + packageParts.length);
+	if (remainder.length === 0) return toNpmReference({ packageName });
+	if (remainder.length === 2 && remainder[0] === 'v') {
+		const version = safeDecodeUriComponent(remainder[1]!);
+		if (!version) return null;
+		if (!isValidNpmVersionOrTag(version)) return null;
+		return toNpmReference({ packageName, version });
+	}
+
+	return null;
+};
+
+export const parseNpmReference = (reference: string): ParsedNpmReference | null =>
+	parseNpmSpecReference(reference) ?? parseNpmUrlReference(reference);
+
+const isNpmPackageUrl = (reference: string): boolean => {
+	const parsedUrl = parseUrl(reference).match({
+		ok: (value) => value,
+		err: () => null
+	});
+	if (!parsedUrl || parsedUrl.protocol !== 'https:') return false;
+	const hostname = parsedUrl.hostname.toLowerCase();
+	if (hostname !== 'npmjs.com' && hostname !== 'www.npmjs.com') return false;
+	const segments = parsedUrl.pathname.split('/').filter((segment) => segment.length > 0);
+	return segments[0] === 'package';
+};
+
 /**
  * Validate a git sparse-checkout search path to prevent injection attacks.
  *
@@ -423,11 +553,19 @@ export const validateResourceReference = (reference: string): ValidationResultWi
 	const nameResult = validateResourceName(reference);
 	if (nameResult.valid) return okWithValue(reference);
 
+	const npmReference = parseNpmReference(reference);
+	if (npmReference) return okWithValue(npmReference.normalizedReference);
+	if (isNpmPackageUrl(reference)) {
+		return failWithValue(
+			`Invalid npm reference: "${reference}". Use npm:<package> or a valid npmjs package URL.`
+		);
+	}
+
 	const gitUrlResult = validateGitUrl(reference);
 	if (gitUrlResult.valid) return gitUrlResult;
 
 	return failWithValue(
-		`Invalid resource reference: "${reference}". Use an existing resource name or a valid HTTPS git URL.`
+		`Invalid resource reference: "${reference}". Use an existing resource name, a valid HTTPS git URL, or an npm reference (npm:<package> or npmjs.com package URL).`
 	);
 };