@danypops/lector 0.1.7 → 0.1.9

package/src/cli.ts

@@ -2,7 +2,7 @@
 import { execFileSync } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { InMemoryWorkspace } from "./adapters/in-memory-workspace.ts";
 import { LocalFilesystemWorkspace } from "./adapters/local-filesystem-workspace.ts";
@@ -11,6 +11,8 @@ import { LECTOR_PATH_NAMES } from "./constants.ts";
 import { serveMain } from "./daemon.ts";
 import type { JobSnapshot } from "./domain/bounded-job-executor.ts";
 import type { ContentHash } from "./domain/content-hash.ts";
+import { DEFAULT_PACKAGE_SOURCE_BOUNDS, type PackageSourceOperationResult } from "./domain/package-source.ts";
+import type { SymbolSearchResult } from "./domain/workspace-symbol.ts";
 import type { WorkspacePort } from "./ports/workspace-port.ts";
 import type { WorkspaceId } from "./service.ts";
 
@@ -51,6 +53,8 @@ const USAGE = `Usage:
   lector workspace git-diff <workspace-id> [--ref <ref>] --max-bytes <n> [--json]
   lector workspace repo-fetch <owner>/<repo>[@ref] [--host <host>] [--json]
     shallow-clones an external repo into a disk-bounded cache and registers it read-only
+  lector package source <project-dir> <package-name> [--version <exact-version>] [--registry <url>] [--json]
+    resolves an installed npm package to verified exact repository source and registers it read-only
   lector workspace search-text <workspace-id> <query> --max-matches <n> --max-bytes <n> [--json]
   lector search symbols <query> [--workspace <id>]... [--timeout-ms <n>] [--json]
   lector search text <query> --max-matches <n> --max-bytes <n> [--workspace <id>]... [--timeout-ms <n>] [--json]
@@ -127,15 +131,26 @@ async function runWorkspaceRegister(dir: string | undefined, flags: string[]): P
 	console.log(hasFlag(flags, "--json") ? JSON.stringify(result) : `${result.workspaceId} (${result.created ? "created" : "already registered"})`);
 }
 
+function formatSymbolSources(result: SymbolSearchResult): readonly string[] {
+	return (result.sources ?? []).map((source) => {
+		const identity = `${source.provenance.languageId}: ${source.status} via ${source.provenance.backend}`;
+		if (source.status === "failed") return source.error ? `${identity} [${source.error.code}] ${source.error.message}` : identity;
+		return `${identity} (${source.symbolCount} symbol${source.symbolCount === 1 ? "" : "s"}${source.truncated ? ", truncated" : ""})`;
+	});
+}
+
 async function runWorkspaceSymbols(workspaceId: string | undefined, query: string | undefined, flags: string[]): Promise<void> {
 	if (!workspaceId || !query) fail(USAGE);
 	const seedFile = flagValue(flags, "--seed-file"); // omit to auto-discover one
 	const client = await connectLectorClient();
-	const { symbols } = await client.call("workspace.findSymbols", { workspaceId, query, seedFile });
+	const result = await client.call("workspace.findSymbols", { workspaceId, query, seedFile });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(symbols));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { symbols, provenance, truncated } = result;
+	console.log(`${provenance.fidelity} via ${provenance.backend}${truncated ? " (truncated)" : ""}`);
+	for (const source of formatSymbolSources(result)) console.log(source);
 	if (symbols.length === 0) {
 		console.log(`no symbols matched "${query}"`);
 		return;
@@ -154,16 +169,22 @@ function parsePosition(line: string | undefined, character: string | undefined):
 	return { line: parsedLine, character: parsedCharacter };
 }
 
+function formatIntelligenceSource(provenance: { fidelity: string; backend: string }): string {
+	return `${provenance.fidelity} via ${provenance.backend}`;
+}
+
 async function runWorkspaceDefinition(workspaceId: string | undefined, path: string | undefined, rest: string[]): Promise<void> {
 	if (!workspaceId || !path) fail(USAGE);
 	const [lineArg, characterArg, ...flags] = rest;
 	const { line, character } = parsePosition(lineArg, characterArg);
 	const client = await connectLectorClient();
-	const { locations } = await client.call("workspace.goToDefinition", { workspaceId, path, line, character });
+	const result = await client.call("workspace.goToDefinition", { workspaceId, path, line, character });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(locations));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { locations, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (locations.length === 0) {
 		console.log("no definition found");
 		return;
@@ -176,11 +197,13 @@ async function runWorkspaceImplementation(workspaceId: string | undefined, path:
 	const [lineArg, characterArg, ...flags] = rest;
 	const { line, character } = parsePosition(lineArg, characterArg);
 	const client = await connectLectorClient();
-	const { locations } = await client.call("workspace.goToImplementation", { workspaceId, path, line, character });
+	const result = await client.call("workspace.goToImplementation", { workspaceId, path, line, character });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(locations));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { locations, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (locations.length === 0) {
 		console.log("no implementation found");
 		return;
@@ -194,11 +217,13 @@ async function runWorkspaceReferences(workspaceId: string | undefined, path: str
 	const { line, character } = parsePosition(lineArg, characterArg);
 	const includeDeclaration = hasFlag(flags, "--include-declaration");
 	const client = await connectLectorClient();
-	const { locations } = await client.call("workspace.findReferences", { workspaceId, path, line, character, includeDeclaration });
+	const result = await client.call("workspace.findReferences", { workspaceId, path, line, character, includeDeclaration });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(locations));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { locations, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (locations.length === 0) {
 		console.log("no references found");
 		return;
@@ -211,22 +236,25 @@ async function runWorkspaceHover(workspaceId: string | undefined, path: string |
 	const [lineArg, characterArg, ...flags] = rest;
 	const { line, character } = parsePosition(lineArg, characterArg);
 	const client = await connectLectorClient();
-	const { hover } = await client.call("workspace.hover", { workspaceId, path, line, character });
+	const result = await client.call("workspace.hover", { workspaceId, path, line, character });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(hover ?? null));
+		console.log(JSON.stringify(result));
 		return;
 	}
-	console.log(hover ? hover.contents : "no hover information available");
+	console.log(formatIntelligenceSource(result.provenance));
+	console.log(result.hover ? result.hover.contents : "no hover information available");
 }
 
 async function runWorkspaceDocumentSymbols(workspaceId: string | undefined, path: string | undefined, flags: string[]): Promise<void> {
 	if (!workspaceId || !path) fail(USAGE);
 	const client = await connectLectorClient();
-	const { symbols } = await client.call("workspace.documentSymbols", { workspaceId, path });
+	const result = await client.call("workspace.documentSymbols", { workspaceId, path });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(symbols));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { symbols, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (symbols.length === 0) {
 		console.log("no symbols found");
 		return;
@@ -241,11 +269,13 @@ async function runWorkspaceDocumentSymbols(workspaceId: string | undefined, path
 async function runWorkspaceDiagnostics(workspaceId: string | undefined, path: string | undefined, flags: string[]): Promise<void> {
 	if (!workspaceId || !path) fail(USAGE);
 	const client = await connectLectorClient();
-	const { diagnostics } = await client.call("workspace.diagnostics", { workspaceId, path });
+	const result = await client.call("workspace.diagnostics", { workspaceId, path });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(diagnostics));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { diagnostics, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (diagnostics.length === 0) {
 		console.log("no diagnostics");
 		return;
@@ -273,11 +303,13 @@ async function runWorkspaceCallHierarchy(
 	const client = await connectLectorClient();
 
 	if (subcommand === "prepare") {
-		const { items } = await client.call("workspace.prepareCallHierarchy", { workspaceId, path, line, character });
+		const result = await client.call("workspace.prepareCallHierarchy", { workspaceId, path, line, character });
 		if (hasFlag(flags, "--json")) {
-			console.log(JSON.stringify(items));
+			console.log(JSON.stringify(result));
 			return;
 		}
+		const { items, provenance } = result;
+		console.log(formatIntelligenceSource(provenance));
 		if (items.length === 0) {
 			console.log("no call-hierarchy root at this position");
 			return;
@@ -286,11 +318,13 @@ async function runWorkspaceCallHierarchy(
 		return;
 	}
 	if (subcommand === "incoming") {
-		const { calls } = await client.call("workspace.incomingCalls", { workspaceId, path, line, character });
+		const result = await client.call("workspace.incomingCalls", { workspaceId, path, line, character });
 		if (hasFlag(flags, "--json")) {
-			console.log(JSON.stringify(calls));
+			console.log(JSON.stringify(result));
 			return;
 		}
+		const { calls, provenance } = result;
+		console.log(formatIntelligenceSource(provenance));
 		if (calls.length === 0) {
 			console.log("no incoming calls found");
 			return;
@@ -299,11 +333,13 @@ async function runWorkspaceCallHierarchy(
 		return;
 	}
 	if (subcommand === "outgoing") {
-		const { calls } = await client.call("workspace.outgoingCalls", { workspaceId, path, line, character });
+		const result = await client.call("workspace.outgoingCalls", { workspaceId, path, line, character });
 		if (hasFlag(flags, "--json")) {
-			console.log(JSON.stringify(calls));
+			console.log(JSON.stringify(result));
 			return;
 		}
+		const { calls, provenance } = result;
+		console.log(formatIntelligenceSource(provenance));
 		if (calls.length === 0) {
 			console.log("no outgoing calls found");
 			return;
@@ -454,6 +490,38 @@ async function runWorkspaceRepoFetch(spec: string | undefined, flags: string[]):
 	if (result.refFallbackOccurred) console.log(`note: requested ref not found, fell back to the default branch (resolved: ${result.resolvedRef})`);
 }
 
+function formatPackageSourceResult(result: PackageSourceOperationResult): string {
+	const { outcome } = result;
+	if (outcome.status === "verified") {
+		return `${result.workspaceId ?? "unregistered"} ${outcome.coordinate.name}@${outcome.coordinate.resolvedVersion} -- ${outcome.workspace.cachePath}\n${outcome.repository.url ?? "local source"}@${outcome.repository.resolvedRef ?? "local"} ${outcome.repository.commit ?? outcome.verification.integrity}`;
+	}
+	if (outcome.status === "ambiguous") {
+		return `ambiguous [${outcome.code}] -- ${outcome.candidates.map((candidate) => `${candidate.version} (${candidate.source})`).join(", ")}${outcome.truncated ? ", …" : ""}`;
+	}
+	if (outcome.status === "unauthenticated") return `unauthenticated [${outcome.code}] -- configure ${outcome.requiredCredentialNames.join(", ")}`;
+	if (outcome.status === "oversized") return `oversized [${outcome.code}] -- ${outcome.resource} exceeded ${outcome.limit}`;
+	if (outcome.status === "mismatched") return `mismatched [${outcome.code}] -- expected ${outcome.expected}, got ${outcome.actual}`;
+	return `unavailable [${outcome.code}]`;
+}
+
+async function runPackageSource(projectDir: string | undefined, packageName: string | undefined, flags: string[]): Promise<void> {
+	if (!projectDir || !packageName) fail(USAGE);
+	const client = await connectLectorClient();
+	const result = await client.call("package.resolveSource", {
+		request: {
+			projectRoot: resolve(projectDir),
+			coordinate: {
+				ecosystem: "npm",
+				registry: flagValue(flags, "--registry") ?? null,
+				name: packageName,
+				requestedVersion: flagValue(flags, "--version") ?? null,
+			},
+		},
+		bounds: DEFAULT_PACKAGE_SOURCE_BOUNDS,
+	});
+	console.log(hasFlag(flags, "--json") ? JSON.stringify(result) : formatPackageSourceResult(result));
+}
+
 async function runWorkspaceSearchText(workspaceId: string | undefined, query: string | undefined, flags: string[]): Promise<void> {
 	if (!workspaceId || !query) fail(USAGE);
 	const maxMatches = requiredIntFlag(flags, "--max-matches");
@@ -655,7 +723,7 @@ WantedBy=default.target
 }
 
 function unitPath(): string {
-	const configHome = process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
+	const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 	return join(configHome, "systemd", "user", LECTOR_PATH_NAMES.systemdUnitName);
 }
 
@@ -713,6 +781,12 @@ async function main(): Promise<void> {
 		fail(USAGE);
 	}
 
+	if (command === "package") {
+		const [action, projectDir, packageName, ...packageFlags] = rest;
+		if (action === "source") return runPackageSource(projectDir, packageName, packageFlags);
+		fail(USAGE);
+	}
+
 	if (command === "workspace") {
 		const [action, ...actionArgs] = rest;
 		if (action === "register") {

package/src/daemon.ts

@@ -9,6 +9,7 @@ import { SqliteSearchCache } from "./adapters/sqlite-search-cache.ts";
 import { SqliteSymbolGraph } from "./adapters/sqlite-symbol-graph.ts";
 import { TieredSearchCache } from "./adapters/tiered-search-cache.ts";
 import { resolveLectorPaths } from "./constants.ts";
+import type { PackageSourceResolverPort } from "./ports/package-source-resolver-port.ts";
 import type { RepoFetcherPort } from "./ports/repo-fetcher-port.ts";
 import type { WorkspacePort } from "./ports/workspace-port.ts";
 import { createLectorService, type LectorService, type OperationName, type WorkspaceId } from "./service.ts";
@@ -84,6 +85,8 @@ export interface LectorDaemonOptions {
 	symbolIndexReapIntervalMs?: number;
 	/** Override the repo.fetch backend (tests inject a GitRepoFetcher pointed at a local fixture repo, avoiding live network). Defaults to a real GitRepoFetcher under this daemon's own data directory. */
 	createRepoFetcher?: () => RepoFetcherPort;
+	/** Override package source resolution while retaining the authenticated daemon/client seam. */
+	createPackageSourceResolver?: () => PackageSourceResolverPort;
 }
 
 function prepare(options: LectorDaemonOptions): {
@@ -110,6 +113,7 @@ function prepare(options: LectorDaemonOptions): {
 		allowDynamicOnly: options.allowDynamicOnly,
 		createSymbolGraph: (workspaceId) => new SqliteSymbolGraph(join(symbolGraphDirectory, `${workspaceId}.db`)),
 		createRepoFetcher: options.createRepoFetcher ?? (() => new GitRepoFetcher(reposDirectory)),
+		createPackageSourceResolver: options.createPackageSourceResolver,
 		// The real production shape the SearchCachePort design was for: an in-memory tier for
 		// speed plus a disk-backed tier so repeated searches survive a daemon restart -- a single
 		// SearchCachePort adapter can only be one or the other, service.ts's own safe default is

package/src/domain/find-workspace-symbols.ts

@@ -1,7 +1,8 @@
 import type { SymbolIndexPort } from "../ports/symbol-index-port.ts";
-import type { WorkspaceSymbol } from "./workspace-symbol.ts";
+import type { SymbolSearchBounds } from "./intelligence-provenance.ts";
+import type { SymbolSearchResult } from "./workspace-symbol.ts";
 
 /** Find workspace symbols matching a fuzzy query string. */
-export async function findWorkspaceSymbols(index: SymbolIndexPort, query: string): Promise<WorkspaceSymbol[]> {
-	return index.findSymbols(query);
+export async function findWorkspaceSymbols(index: SymbolIndexPort, query: string, bounds?: SymbolSearchBounds): Promise<SymbolSearchResult> {
+	return index.findSymbols(query, bounds);
 }

package/src/domain/installed-package-version.ts

@@ -0,0 +1,66 @@
+export type JavaScriptPackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+export interface InstalledPackageVersionRequest {
+	readonly projectRoot: string;
+	readonly packageName: string;
+	readonly requestedVersion: string | null;
+}
+
+export interface InstalledPackageVersionBounds {
+	readonly maxManifestBytes: number;
+	readonly maxManifestEntries: number;
+	readonly maxManifestNesting: number;
+	readonly maxWorkspaces: number;
+	readonly maxDiagnostics: number;
+	readonly maxCandidates: number;
+	readonly maxEvidencePerVersion: number;
+}
+
+export interface InstalledPackageEvidence {
+	readonly manager: JavaScriptPackageManager;
+	readonly lockfile: string;
+	readonly locator: string;
+	readonly integrity: string | null;
+	readonly workspace: boolean;
+}
+
+export interface ResolvedInstalledPackageVersion {
+	readonly status: "resolved";
+	readonly packageName: string;
+	readonly requestedVersion: string | null;
+	readonly version: string;
+	readonly evidence: readonly InstalledPackageEvidence[];
+	readonly evidenceTruncated: boolean;
+}
+
+export interface InstalledPackageVersionCandidate {
+	readonly version: string;
+	readonly evidence: readonly InstalledPackageEvidence[];
+	readonly evidenceTruncated: boolean;
+}
+
+export interface AmbiguousInstalledPackageVersion {
+	readonly status: "ambiguous";
+	readonly packageName: string;
+	readonly requestedVersion: null;
+	readonly candidates: readonly InstalledPackageVersionCandidate[];
+	readonly truncated: boolean;
+}
+
+export interface UnavailableInstalledPackageVersion {
+	readonly status: "unavailable";
+	readonly code: "lockfile-not-found" | "package-not-found" | "version-not-found" | "unsupported-lockfile" | "corrupt-lockfile";
+	readonly lockfile?: string;
+}
+
+export interface OversizedInstalledPackageVersion {
+	readonly status: "oversized";
+	readonly resource: "manifest-bytes" | "manifest-entries" | "manifest-nesting" | "workspaces" | "diagnostics";
+	readonly limit: number;
+}
+
+export type InstalledPackageVersionOutcome =
+	| ResolvedInstalledPackageVersion
+	| AmbiguousInstalledPackageVersion
+	| UnavailableInstalledPackageVersion
+	| OversizedInstalledPackageVersion;

package/src/domain/intelligence-provenance.ts

@@ -0,0 +1,27 @@
+export type IntelligenceFidelity = "semantic" | "structural";
+
+export interface IntelligenceProvenance {
+	readonly fidelity: IntelligenceFidelity;
+	readonly backend: string;
+	readonly languageId: string;
+	readonly authority: "language-server" | "parser" | "compiler";
+	readonly freshness: "live-process" | "content-hash" | "filesystem-snapshot";
+	readonly limitations: readonly string[];
+}
+
+export interface IntelligenceSourceOutcome {
+	readonly provenance: IntelligenceProvenance;
+	readonly status: "ready" | "failed";
+	readonly symbolCount: number;
+	readonly truncated?: boolean;
+	readonly error?: { readonly code: string; readonly message: string };
+}
+
+export interface SymbolSearchBounds {
+	readonly maxResults: number;
+}
+
+export interface ProvenancedResult<T> {
+	readonly result: T;
+	readonly provenance: IntelligenceProvenance;
+}

package/src/domain/language-server-descriptor.ts

@@ -13,13 +13,18 @@ export type LanguageServerLaunch = { readonly kind: "npm-module"; readonly entry
 
 export interface LanguageServerDescriptor {
 	readonly languageId: string;
+	readonly backendId: string;
 	readonly extensions: readonly string[];
+	/** Per-extension document language ids when one server owns a language family. */
+	readonly documentLanguageIds?: Readonly<Record<string, string>>;
 	readonly launch: LanguageServerLaunch;
 	readonly args: readonly string[];
 	/** Checked nearest-first; closest match wins over a more distant one -- a monorepo subproject with its own root marker resolves to itself, not the outer repo. */
 	readonly rootMarkers: readonly string[];
 	/** Tried before the bounded directory scan when picking a file to warm the server with (e.g. a language's usual entry-point names). */
 	readonly commonSeedCandidates: readonly string[];
+	/** Excludes unsafe or unusually expensive servers from automatic workspace-wide fan-out while preserving explicit file operations. */
+	readonly workspaceDiscovery?: "enabled" | "explicit-only";
 	/** Extra textDocument/workspace capabilities this specific server gates real features behind (e.g. typescript-language-server withholds diagnostics/callHierarchy unless declared). */
 	readonly extraCapabilities?: Record<string, unknown>;
 	/** Milliseconds to wait after opening a file before trusting the server's answers -- no server signals "project loaded". Default 1000ms; rust-analyzer needs more (see RUST_DESCRIPTOR). */
@@ -30,7 +35,16 @@ export const DEFAULT_SETTLE_MS = 1000;
 
 export const TYPESCRIPT_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "typescript",
+	backendId: "typescript-language-server",
 	extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+	documentLanguageIds: {
+		".ts": "typescript",
+		".tsx": "typescriptreact",
+		".js": "javascript",
+		".jsx": "javascriptreact",
+		".mjs": "javascript",
+		".cjs": "javascript",
+	},
 	launch: { kind: "npm-module", entryModule: "typescript-language-server/lib/cli.mjs" },
 	args: ["--stdio"],
 	rootMarkers: ["tsconfig.json", "jsconfig.json", "package.json"],
@@ -43,6 +57,7 @@ export const TYPESCRIPT_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const PYTHON_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "python",
+	backendId: "pyright",
 	extensions: [".py", ".pyi"],
 	launch: { kind: "npm-module", entryModule: "pyright/langserver.index.js" },
 	args: ["--stdio"],
@@ -52,6 +67,7 @@ export const PYTHON_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const GO_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "go",
+	backendId: "gopls",
 	extensions: [".go"],
 	// gopls ships via `go install`, not npm.
 	launch: { kind: "system-binary", command: "gopls" },
@@ -62,6 +78,7 @@ export const GO_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const RUST_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "rust",
+	backendId: "rust-analyzer",
 	extensions: [".rs"],
 	// rust-analyzer ships via rustup, not npm.
 	launch: { kind: "system-binary", command: "rust-analyzer" },
@@ -73,6 +90,7 @@ export const RUST_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const CPP_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "cpp",
+	backendId: "clangd",
 	extensions: [".c", ".h", ".cc", ".cpp", ".cxx", ".hh", ".hpp", ".hxx"],
 	// clangd ships via LLVM's system packaging, not npm.
 	launch: { kind: "system-binary", command: "clangd" },
@@ -83,7 +101,9 @@ export const CPP_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const BASH_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "shellscript",
+	backendId: "bash-language-server",
 	extensions: [".sh", ".bash"],
+	workspaceDiscovery: "explicit-only",
 	launch: { kind: "npm-module", entryModule: "bash-language-server/out/cli.js" },
 	args: ["start"],
 	rootMarkers: [],
@@ -92,7 +112,9 @@ export const BASH_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const YAML_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "yaml",
+	backendId: "yaml-language-server",
 	extensions: [".yaml", ".yml"],
+	workspaceDiscovery: "explicit-only",
 	launch: { kind: "npm-module", entryModule: "yaml-language-server/bin/yaml-language-server" },
 	args: ["--stdio"],
 	rootMarkers: [],

package/src/domain/npm-package-metadata.ts

@@ -0,0 +1,26 @@
+export interface NpmRegistryVersionRequest {
+	readonly registry: string;
+	readonly name: string;
+	readonly version: string;
+}
+
+export interface NpmRegistryBounds {
+	readonly maxResponseBytes: number;
+	readonly maxRedirects: number;
+	readonly maxRetries: number;
+	readonly timeoutMs: number;
+}
+
+export interface NpmRepositoryMetadata {
+	readonly type: string | null;
+	readonly url: string;
+	readonly directory: string | null;
+}
+
+export interface NpmPackageVersionMetadata {
+	readonly name: string;
+	readonly version: string;
+	readonly repository: NpmRepositoryMetadata | null;
+	readonly gitHead: string | null;
+	readonly integrity: string | null;
+}

package/src/domain/package-source.ts

@@ -0,0 +1,143 @@
+export type PackageEcosystem = "npm" | "pypi" | "cargo" | "go" | "maven" | "conan" | "vcpkg" | "nuget" | "swiftpm";
+
+export interface PackageCoordinateRequest {
+	readonly ecosystem: PackageEcosystem;
+	readonly registry: string | null;
+	readonly name: string;
+	readonly requestedVersion: string | null;
+}
+
+export interface PackageSourceRequest {
+	readonly projectRoot: string;
+	readonly coordinate: PackageCoordinateRequest;
+}
+
+export interface PackageSourceBounds {
+	readonly maxManifestBytes: number;
+	readonly maxManifestEntries: number;
+	readonly maxManifestNesting: number;
+	readonly maxWorkspaces: number;
+	readonly maxDiagnostics: number;
+	readonly maxRegistryResponseBytes: number;
+	readonly maxRedirects: number;
+	readonly maxRetries: number;
+	readonly maxCloneBytes: number;
+	readonly maxCacheBytes: number;
+	readonly maxCandidates: number;
+	readonly timeoutMs: number;
+}
+
+export interface ResolvedPackageCoordinate extends PackageCoordinateRequest {
+	readonly resolvedVersion: string;
+}
+
+export interface PackageRepositoryIdentity {
+	readonly url: string | null;
+	readonly requestedRef: string | null;
+	readonly resolvedRef: string | null;
+	readonly commit: string | null;
+}
+
+export interface PackageSourceWorkspace {
+	readonly cachePath: string;
+	readonly origin: "local" | "fetched";
+	readonly readOnly: true;
+}
+
+export type PackageSourceVerificationMethod = "lockfile-vcs-pin" | "registry-metadata-and-commit" | "source-artifact-checksum" | "local-content-digest";
+
+export interface PackageSourceVerification {
+	readonly status: "verified";
+	readonly method: PackageSourceVerificationMethod;
+	readonly integrity: string;
+}
+
+export interface VerifiedPackageSource {
+	readonly status: "verified";
+	readonly coordinate: ResolvedPackageCoordinate;
+	readonly repository: PackageRepositoryIdentity;
+	readonly workspace: PackageSourceWorkspace;
+	readonly verification: PackageSourceVerification;
+}
+
+export type PackageSourceUnavailableCode =
+	| "package-not-found"
+	| "version-not-found"
+	| "source-metadata-missing"
+	| "unsupported-ecosystem"
+	| "unsupported-manifest"
+	| "unverifiable-source";
+
+export interface UnavailablePackageSource {
+	readonly status: "unavailable";
+	readonly code: PackageSourceUnavailableCode;
+}
+
+export interface PackageSourceCandidate {
+	readonly version: string;
+	readonly source: string;
+}
+
+export interface AmbiguousPackageSource {
+	readonly status: "ambiguous";
+	readonly code: "multiple-installed-versions" | "multiple-source-candidates";
+	readonly candidates: readonly PackageSourceCandidate[];
+	readonly truncated: boolean;
+}
+
+export interface UnauthenticatedPackageSource {
+	readonly status: "unauthenticated";
+	readonly code: "registry-authentication-required" | "repository-authentication-required";
+	readonly requiredCredentialNames: readonly string[];
+}
+
+export interface OversizedPackageSource {
+	readonly status: "oversized";
+	readonly code: "manifest-limit-exceeded" | "registry-response-limit-exceeded" | "clone-limit-exceeded" | "cache-limit-exceeded";
+	readonly resource:
+		| "manifest-bytes"
+		| "manifest-entries"
+		| "manifest-nesting"
+		| "workspaces"
+		| "diagnostics"
+		| "registry-response-bytes"
+		| "clone-bytes"
+		| "cache-bytes";
+	readonly limit: number;
+	readonly observed: number | null;
+}
+
+export interface MismatchedPackageSource {
+	readonly status: "mismatched";
+	readonly code: "coordinate-mismatch" | "repository-ref-mismatch" | "repository-commit-mismatch" | "integrity-mismatch";
+	readonly expected: string;
+	readonly actual: string;
+}
+
+export type PackageSourceOutcome =
+	| VerifiedPackageSource
+	| UnavailablePackageSource
+	| AmbiguousPackageSource
+	| UnauthenticatedPackageSource
+	| OversizedPackageSource
+	| MismatchedPackageSource;
+
+export interface PackageSourceOperationResult {
+	readonly outcome: PackageSourceOutcome;
+	readonly workspaceId: string | null;
+}
+
+export const DEFAULT_PACKAGE_SOURCE_BOUNDS: PackageSourceBounds = {
+	maxManifestBytes: 16 * 1024 * 1024,
+	maxManifestEntries: 100_000,
+	maxManifestNesting: 128,
+	maxWorkspaces: 10_000,
+	maxDiagnostics: 100,
+	maxRegistryResponseBytes: 8 * 1024 * 1024,
+	maxRedirects: 5,
+	maxRetries: 2,
+	maxCloneBytes: 512 * 1024 * 1024,
+	maxCacheBytes: 5 * 1024 * 1024 * 1024,
+	maxCandidates: 20,
+	timeoutMs: 60_000,
+};